cdc.hpp

Go to the documentation of this file.

#pragma once
/**
 * @file cdc.hpp
 * @brief USB CDC (Virtual COM Port) interface
 *
 * Provides serial communication over USB CDC ACM class.
 * Shows up as a COM port on the host - works with any terminal.
 *
 * Usage:
 *   #include <sbl/usb/cdc.hpp>
 *
 *   sbl::usb::CdcSerial::puts("Hello USB!\n");
 *
 *   if (sbl::usb::CdcSerial::available()) {
 *       char c = sbl::usb::CdcSerial::read_byte();
 *   }
 *
 * For logging integration:
 *   using Logger = sbl::log::Logger<sbl::usb::CdcOutput, Timer>;
 */
 
#include <cstddef>
#include <cstdint>
 
namespace sbl::usb {
 
/**
 * @brief USB CDC (Virtual COM Port) interface
 *
 * Static class providing serial I/O over USB CDC.
 * All operations are non-blocking unless noted.
 *
 * @note read/available/connected are ISR-safe (TinyUSB buffer ops).
 *       write/puts/write_byte are NOT ISR-safe — may call tud_task().
 *       flush() is NOT ISR-safe — blocks until TX complete.
 */
class CdcSerial {
public:
    /**
     * @brief Write data to USB serial (non-blocking)
     *
     * May call tud_task() internally to flush — NOT ISR-safe.
     *
     * @param data Pointer to data buffer
     * @param len Number of bytes to write
     * @return Number of bytes written (may be less than len if buffer full)
     */
    static size_t write(const uint8_t* data, size_t len);
 
    /**
     * @brief Write null-terminated string
     * @param str String to write
     * @return Number of bytes written
     */
    static size_t puts(const char* str);
 
    /**
     * @brief Write single byte
     * @param byte Byte to write
     * @return true if byte was written, false if buffer full
     */
    static bool write_byte(uint8_t byte);
 
    /**
     * @brief Read data from USB serial (non-blocking)
     * @param data Buffer to read into
     * @param max_len Maximum bytes to read
     * @return Number of bytes read
     */
    static size_t read(uint8_t* data, size_t max_len);
 
    /**
     * @brief Read single byte
     * @return Byte read, or -1 if none available
     */
    static int read_byte();
 
    /**
     * @brief Get number of bytes available to read
     * @return Bytes available in receive buffer
     */
    static size_t available();
 
    /**
     * @brief Check if host has terminal connected (DTR set)
     *
     * Returns true when a host terminal has opened the port and set DTR.
     * This is more reliable than just checking tud_ready() which only
     * indicates USB enumeration, not that a terminal is actually listening.
     *
     * @return true if host terminal is connected
     */
    static bool connected();
 
    /**
     * @brief Check if a terminal just connected (DTR rising edge)
     *
     * Returns true exactly once per DTR low→high transition. Use this
     * to send boot banners or one-time status messages when a terminal
     * opens the port.
     *
     * @return true once per new connection
     */
    static bool just_connected();
 
    /**
     * @brief Flush TX buffer
     *
     * Blocks until all pending data is sent or timeout.
     */
    static void flush();
};
 
/**
 * @brief Logger output sink for sbl::log integration
 *
 * Usage:
 *   using Logger = sbl::log::Logger<sbl::usb::CdcOutput, MyTimer>;
 *
 *   #define SBL_LOG_LEVEL SBL_LOG_LEVEL_DEBUG
 *   #define SblLogger_ Logger
 *   #include <sbl/log/macros.hpp>
 *
 *   SBL_LOG_INFO("Hello from USB!");
 */
struct CdcOutput {
    static void write(const char* str) {
        CdcSerial::puts(str);
    }
};
 
} // namespace sbl::usb