usb_uart.h

Go to the documentation of this file.

#pragma once
 
#if defined(USE_ESP32_VARIANT_ESP32P4) || defined(USE_ESP32_VARIANT_ESP32S2) || defined(USE_ESP32_VARIANT_ESP32S3) || \
    defined(USE_ESP32_VARIANT_ESP32S31) || defined(USE_ESP32_VARIANT_ESP32H4)
#include "esphome/core/component.h"
#include "esphome/core/helpers.h"
#include "esphome/core/string_ref.h"
#include "esphome/components/uart/uart_component.h"
#include "esphome/components/usb_host/usb_host.h"
#include "esphome/core/lock_free_queue.h"
#include "esphome/core/event_pool.h"
#include "esphome/core/log.h"
#include <array>
#include <atomic>
#include <functional>
 
namespace esphome::usb_uart {
 
class USBUartTypeCdcAcm;
class USBUartComponent;
class USBUartChannelBase;
class USBUartTypePL2303;
 
ESPHOME_LOG_TAG(TAG, "usb_uart");
 
static constexpr uint8_t USB_CDC_SUBCLASS_ACM = 0x02;
static constexpr uint8_t USB_SUBCLASS_COMMON = 0x02;
static constexpr uint8_t USB_SUBCLASS_NULL = 0x00;
static constexpr uint8_t USB_PROTOCOL_NULL = 0x00;
static constexpr uint8_t USB_DEVICE_PROTOCOL_IAD = 0x01;
static constexpr uint8_t USB_VENDOR_IFC = usb_host::USB_TYPE_VENDOR | usb_host::USB_RECIP_INTERFACE;
static constexpr uint8_t USB_VENDOR_DEV = usb_host::USB_TYPE_VENDOR | usb_host::USB_RECIP_DEVICE;
 
struct CdcEps {
  const usb_ep_desc_t *notify_ep;
  const usb_ep_desc_t *in_ep;
  const usb_ep_desc_t *out_ep;
  // 0xFF marks a channel that was never matched to a CDC function on the device
  uint8_t bulk_interface_number{0xFF};
  // Also the wIndex target for CDC class requests (SET_LINE_CODING etc.), so it
  // must remain valid even when the interface itself is not claimed.
  uint8_t interrupt_interface_number{0xFF};
  bool interrupt_interface_claimed{false};
  // bInterfaceClass of each interface above, which decides how a host binds the port
  uint8_t bulk_interface_class{0};
  uint8_t interrupt_interface_class{0};
};
 
enum CH34xChipType : uint8_t {
  CHIP_CH342F = 0,
  CHIP_CH342K,
  CHIP_CH343GP,
  CHIP_CH343G_AUTOBAUD,
  CHIP_CH343K,
  CHIP_CH343J,
  CHIP_CH344L,
  CHIP_CH344L_V2,
  CHIP_CH344Q,
  CHIP_CH347TF,
  CHIP_CH9101UH,
  CHIP_CH9101RY,
  CHIP_CH9102F,
  CHIP_CH9102X,
  CHIP_CH9103M,
  CHIP_CH9104L,
  CHIP_CH340B,
  CHIP_CH339W,
  CHIP_CH9111L_M0,
  CHIP_CH9111L_M1,
  CHIP_CH9114L,
  CHIP_CH9114W,
  CHIP_CH9114F,
  CHIP_CH346C_M0,
  CHIP_CH346C_M1,
  CHIP_CH346C_M2,
  CHIP_UNKNOWN = 0xFF,
};
 
// 1 and 2 are the stop bit count the uart component uses, so a count set through the
// UARTComponent API (as serial_proxy does) means the same here. 1.5 has no count.
enum UARTStopBitsOptions {
  UART_CONFIG_STOP_BITS_1 = 1,
  UART_CONFIG_STOP_BITS_2 = 2,
  UART_CONFIG_STOP_BITS_1_5 = 3,
};
 
// Stop bits and parity as adapters take them on the wire: CDC SET_LINE_CODING, and the
// CP210x, FTDI and PL2303 requests, all use these values
enum class LineStopBits : uint8_t {
  LINE_STOP_BITS_1 = 0,
  LINE_STOP_BITS_1_5 = 1,
  LINE_STOP_BITS_2 = 2,
};
 
enum class LineParity : uint8_t {
  LINE_PARITY_NONE = 0,
  LINE_PARITY_ODD = 1,
  LINE_PARITY_EVEN = 2,
  LINE_PARITY_MARK = 3,
  LINE_PARITY_SPACE = 4,
};
 
// Indexed by LineParity
static const char *const PARITY_NAMES[] = {"NONE", "ODD", "EVEN", "MARK", "SPACE"};
// Indexed by LineStopBits
static const char *const STOP_BITS_NAMES[] = {"1", "1.5", "2"};
 
enum class ConfigMode : uint8_t {
  CONFIG_MODE_INIT,    
  CONFIG_MODE_RELOAD,  
  CONFIG_MODE_MODEM,   
};
 
class RingBuffer {
 public:
  RingBuffer(uint16_t buffer_size) : buffer_size_(buffer_size), buffer_(new uint8_t[buffer_size]) {}
  bool is_empty() const { return this->read_pos_ == this->insert_pos_; }
  size_t get_available() const {
    return (this->insert_pos_ + this->buffer_size_ - this->read_pos_) % this->buffer_size_;
  };
  size_t get_free_space() const { return this->buffer_size_ - 1 - this->get_available(); }
  uint8_t peek() const { return this->buffer_[this->read_pos_]; }
  void push(uint8_t item);
  void push(const uint8_t *data, size_t len);
  uint8_t pop();
  size_t pop(uint8_t *data, size_t len);
  void clear() { this->read_pos_ = this->insert_pos_ = 0; }
 
 protected:
  uint16_t insert_pos_ = 0;
  uint16_t read_pos_ = 0;
  uint16_t buffer_size_;
  uint8_t *buffer_;
};
 
// Structure for queuing received USB data chunks
struct UsbDataChunk {
  uint8_t data[usb_host::USB_MAX_PACKET_SIZE];
  uint16_t length;
  USBUartChannelBase *channel;
 
  // Required for EventPool - no cleanup needed for POD types
  void release() {}
};
 
// Structure for queuing outgoing USB data chunks (one per USB packet)
struct UsbOutputChunk {
  static constexpr size_t MAX_CHUNK_SIZE = usb_host::USB_MAX_PACKET_SIZE;
  uint8_t data[MAX_CHUNK_SIZE];
  uint16_t length;
 
  // Required for EventPool - no cleanup needed for POD types
  void release() {}
};
 
// Common, non-final base for all USB UART channel implementations.
// Concrete channel types (USBUartChannel for CDC-style devices, vendor-specific
// multiplexed channels like CH934X) derive from this and are themselves final,
// per the "configurable classes are final" convention.
class USBUartChannelBase : public uart::UARTComponent, public Parented<USBUartComponent> {
  friend class USBUartComponent;
  friend class USBUartTypeCdcAcm;
  friend class USBUartTypeCP210X;
  friend class USBUartTypeCH34X;
  friend class USBUartTypeFT23XX;
  friend class USBUartTypePL2303;
 
 public:
  // Number of output chunk slots per channel, derived from buffer_size config.
  // Computed as ceil(buffer_size / 64) + 1 in Python codegen; defaults to 5 (256 / 64 + 1).
  static constexpr uint8_t USB_OUTPUT_CHUNK_COUNT = USB_UART_OUTPUT_CHUNK_COUNT;
 
  void write_array(const uint8_t *data, size_t len) override;
  bool peek_byte(uint8_t *data) override;
  bool read_array(uint8_t *data, size_t len) override;
  size_t available() override { return this->input_buffer_.get_available(); }
  bool is_connected() override { return this->initialised_.load(); }
  uart::UARTFlushResult flush() override;
  // Re-apply the current line settings (baud, parity, etc) to this already-open channel.
  void load_settings(bool dump_config) override;
  using UARTComponent::load_settings;  // also bring in the no-arg overload for convenience
  void set_debug(bool debug) { this->debug_ = debug; }
  void set_dummy_receiver(bool dummy_receiver) { this->dummy_receiver_ = dummy_receiver; }
  void set_debug_prefix(const char *prefix) { this->debug_prefix_ = StringRef(prefix); }
  void set_flush_timeout(uint32_t flush_timeout_ms) override { this->flush_timeout_ms_ = flush_timeout_ms; }
 
  void set_rx_callback(std::function<void()> cb) { this->rx_callback_ = std::move(cb); }
 
  uint8_t get_interface_number() const {
    return this->cdc_dev_.interrupt_interface_number != 0xFF ? this->cdc_dev_.interrupt_interface_number
                                                             : this->cdc_dev_.bulk_interface_number;
  }
 
  uint8_t get_interface_class() const {
    return this->cdc_dev_.interrupt_interface_number != 0xFF ? this->cdc_dev_.interrupt_interface_class
                                                             : this->cdc_dev_.bulk_interface_class;
  }
 
  uint8_t get_port_number() const { return 0; }
 
  bool set_modem_control(bool dtr, bool rts);
  bool get_dtr() const { return this->dtr_; }
  bool get_rts() const { return this->rts_; }
 
 protected:
  // Not directly instantiable; construct a concrete channel type instead.
  USBUartChannelBase(uint8_t index, uint16_t buffer_size) : input_buffer_(RingBuffer(buffer_size)), index_(index) {}
  void check_logger_conflict() override {}
  LineStopBits line_stop_bits_() const;
  LineParity line_parity_() const;
  // Larger structures first (8+ bytes)
  RingBuffer input_buffer_;
  LockFreeQueue<UsbOutputChunk, USB_OUTPUT_CHUNK_COUNT> output_queue_;
  // Pool sized to queue capacity (SIZE-1) because LockFreeQueue<T,N> is a ring
  // buffer that holds N-1 elements. This guarantees allocate() returns nullptr
  // before push() can fail, preventing a pool slot leak.
  EventPool<UsbOutputChunk, USB_OUTPUT_CHUNK_COUNT - 1> output_pool_;
  std::function<void()> rx_callback_{};
  CdcEps cdc_dev_{};
  StringRef debug_prefix_{};
  // 4-byte fields
  uint32_t flush_timeout_ms_{100};
  // 1-byte fields (no padding between groups)
  std::atomic<bool> input_started_{true};
  std::atomic<bool> output_started_{true};
  std::atomic<bool> initialised_{false};
  const uint8_t index_;
  bool debug_{};
  bool dummy_receiver_{};
  // Asserted whenever a device connects, as a host driver does when it opens the port
  bool dtr_{true};
  bool rts_{true};
  // Line settings or DTR/RTS changed while the config machine was busy; sent once it is idle
  bool reload_pending_{false};
  bool modem_pending_{false};
};
 
// Concrete channel type for CDC-style USB serial devices (2 bulk endpoints per
// channel). All shared behavior lives in USBUartChannelBase.
class USBUartChannel final : public USBUartChannelBase {
 public:
  USBUartChannel(uint8_t index, uint16_t buffer_size) : USBUartChannelBase(index, buffer_size) {}
};
 
class USBUartComponent : public usb_host::USBClient {
 public:
  USBUartComponent(uint16_t vid, uint16_t pid) : usb_host::USBClient(vid, pid) {}
  void setup() override;
  void loop() override;
  void dump_config() override;
  std::vector<USBUartChannelBase *> get_channels() { return this->channels_; }
 
  void add_channel(USBUartChannelBase *channel) { this->channels_.push_back(channel); }
 
  virtual void start_input(USBUartChannelBase *channel);
  void start_output(USBUartChannelBase *channel);
 
  // Begin configuring all channels (full initialisation). Called from on_connected().
  void enable_channels();
  // Re-apply line settings to a single, already-open channel (used by
  // USBUartChannelBase::load_settings()).
  void apply_channel_settings(USBUartChannelBase *channel);
  // Apply the DTR/RTS state of a single, already-open channel (used by
  // USBUartChannelBase::set_modem_control()).
  void apply_modem_control(USBUartChannelBase *channel);
 
  // Called from loop() when input_buffer_ has insufficient space for the incoming chunk.
  // Default is a no-op; override in device-specific subclasses that need resync on overflow.
  virtual void on_rx_overflow(USBUartChannelBase *channel) {}
 
  // Lock-free data transfer from USB task to main loop
  static constexpr int USB_DATA_QUEUE_SIZE = 32;
  LockFreeQueue<UsbDataChunk, USB_DATA_QUEUE_SIZE> usb_data_queue_;
  // Pool sized to queue capacity (SIZE-1) — see USBUartChannelBase::output_pool_ comment.
  EventPool<UsbDataChunk, USB_DATA_QUEUE_SIZE - 1> chunk_pool_;
 
 protected:
  // Issue one control transfer as part of the setup state machine. The completion
  // callback (USB-task context) records the result/IN data, marks the step done and
  // wakes the loop so run_config_machine_() advances on the loop thread. Call exactly
  // once from config_step_()/config_device_step_() when issuing a step.
  // An IN reply goes to cfg_response_, or to `dest` when set. A `dest` reply must be
  // exactly data.size() bytes, else the step fails.
  void config_transfer_(uint8_t type, uint8_t request, uint16_t value, uint16_t index,
                        const std::vector<uint8_t> &data = {}, uint8_t *dest = nullptr);
  // (Re)start the config state machine. INIT runs over all channels; the other modes act
  // on cfg_single_ only.
  void start_config_(ConfigMode mode);
  // Advance the config state machine; called from loop(). Returns true if it did work.
  bool run_config_machine_();
 
  // Per-subclass per-channel settings sequence. For the given zero-based step, issue the
  // next control transfer via config_transfer_() and return true, or return false when the
  // channel has no more steps. reload=true ⇒ apply only baud/parity/stop/data (skip
  // enable/reset/DTR-RTS). ok/response carry the previous step's result and IN data.
  virtual bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok,
                           const uint8_t *response) = 0;
  // Optional one-time device-level setup run before the per-channel phase on init only
  // (e.g. CH34x chip detection). Same contract as config_step_(). Default: no steps.
  virtual bool config_device_step(uint8_t step, bool ok, const uint8_t *response) { return false; }
  // Issue the one control transfer, via config_transfer_(), that puts the channel's dtr_
  // and rts_ on the wire.
  virtual void modem_control_transfer(USBUartChannelBase *channel) = 0;
 
  // The device is only usable once the config machine has applied every channel's line
  // settings, so the connected report waits for run_config_machine_() to finish the init
  bool reports_connection_itself() const override { return true; }
 
  std::vector<USBUartChannelBase *> channels_{};
 
  // Config state machine
  USBUartChannelBase *cfg_single_{nullptr};  // non-null: single-channel run (RELOAD or MODEM)
  uint8_t *cfg_read_dest_{nullptr};          // where the step in flight stores its reply, if not cfg_response_
  size_t cfg_read_len_{0};                   // and the exact length it then expects
  // synchronizes cfg_ok_/cfg_response_ across threads; a byte, since atomic<bool> does not inline on Xtensa
  std::atomic<uint8_t> cfg_done_{0};
  uint8_t cfg_response_[8]{};  // last IN transfer payload
  uint8_t cfg_channel_idx_{0};
  uint8_t cfg_step_{0};
  ConfigMode cfg_mode_{ConfigMode::CONFIG_MODE_INIT};
  bool cfg_active_{false};
  bool cfg_device_phase_{false};
  bool cfg_in_flight_{false};
  bool cfg_ok_{true};
};
 
class USBUartTypeCdcAcm : public USBUartComponent {
 public:
  USBUartTypeCdcAcm(uint16_t vid, uint16_t pid) : USBUartComponent(vid, pid) {}
  void set_claim_comm_interface(bool claim) { this->claim_comm_interface_ = claim; }
 
 protected:
  virtual std::vector<CdcEps> parse_descriptors(usb_device_handle_t dev_hdl);
  void on_connected() override;
  void on_disconnected() override;
  bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok, const uint8_t *response) override;
  void modem_control_transfer(USBUartChannelBase *channel) override;
  // Each claimed interface pins one host hardware channel per endpoint; skipping
  // the comm (interrupt) interface frees one on channel-poor hosts (ESP32-S3: 8).
  bool claim_comm_interface_{true};
};
 
// The block GET_FLOW and SET_FLOW transfer, little-endian on the wire as in memory
struct CP210xFlowBlock {
  uint32_t control_handshake;
  uint32_t flow_replace;
  uint32_t xon_limit;
  uint32_t xoff_limit;
};
 
class USBUartTypeCP210X : public USBUartTypeCdcAcm {
 public:
  USBUartTypeCP210X(uint16_t vid, uint16_t pid) : USBUartTypeCdcAcm(vid, pid) {}
 
 protected:
  // Matches max_channels of the CP210X type in __init__.py
  static constexpr uint8_t MAX_CHANNELS = 3;
 
  std::vector<CdcEps> parse_descriptors(usb_device_handle_t dev_hdl) override;
  bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok, const uint8_t *response) override;
  void modem_control_transfer(USBUartChannelBase *channel) override;
  bool config_device_step(uint8_t step, bool ok, const uint8_t *response) override;
  void set_flow_transfer_(USBUartChannelBase *channel);
 
  // The block last read for each channel, so a DTR/RTS change under RTS/CTS is a single SET_FLOW
  std::array<CP210xFlowBlock, MAX_CHANNELS> flow_blocks_{};
  // A CP2102N whose firmware has erratum E104
  bool no_flow_control_{false};
};
class USBUartTypeCH34X : public USBUartTypeCdcAcm {
 public:
  USBUartTypeCH34X(uint16_t vid, uint16_t pid) : USBUartTypeCdcAcm(vid, pid) {
    // ch34x doesn't use the interrupt endpoint, and we don't have endpoints to spare. The
    // comm interface is left in place unclaimed: on the CDC-style chips it is still the
    // interface a host binds, and so the one the port is identified by.
    this->claim_comm_interface_ = false;
  }
  void dump_config() override;
 
 protected:
  bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok, const uint8_t *response) override;
  void modem_control_transfer(USBUartChannelBase *channel) override;
  bool config_device_step(uint8_t step, bool ok, const uint8_t *response) override;
 
 private:
  CH34xChipType chiptype_{CHIP_UNKNOWN};
  const char *chip_name_{"unknown"};
  uint8_t num_ports_{1};
};
 
class USBUartTypeFT23XX : public USBUartTypeCdcAcm {
 public:
  USBUartTypeFT23XX(uint16_t vid, uint16_t pid) : USBUartTypeCdcAcm(vid, pid) {}
 
  void start_input(USBUartChannelBase *channel) override;
  void on_rx_overflow(USBUartChannelBase *channel) override;
 
 protected:
  std::vector<CdcEps> parse_descriptors(usb_device_handle_t dev_hdl) override;
  bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok, const uint8_t *response) override;
  void modem_control_transfer(USBUartChannelBase *channel) override;
 
  uint8_t chip_type_{255};
};
 
enum Pl2303ChipType : uint8_t {
  PL2303_TYPE_H = 0,  // Legacy, max 1.2Mbaud
  PL2303_TYPE_HX,     // max 6Mbaud, divisor encoding
  PL2303_TYPE_TA,     // max 6Mbaud, alt divisor encoding
  PL2303_TYPE_TB,     // max 12Mbaud, alt divisor encoding
  PL2303_TYPE_HXD,    // max 12Mbaud, divisor encoding
  PL2303_TYPE_HXN,    // G-series, max 12Mbaud, direct encoding only
  PL2303_TYPE_UNKNOWN = 0xFF,
};
 
class USBUartTypePL2303 : public USBUartTypeCdcAcm {
  friend class USBUartChannelBase;
 
 public:
  USBUartTypePL2303(uint16_t vid, uint16_t pid) : USBUartTypeCdcAcm(vid, pid) {}
 
 protected:
  std::vector<CdcEps> parse_descriptors(usb_device_handle_t dev_hdl) override;
  bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok, const uint8_t *response) override;
  void modem_control_transfer(USBUartChannelBase *channel) override;
 
  Pl2303ChipType chip_type_{PL2303_TYPE_UNKNOWN};
};
 
}  // namespace esphome::usb_uart
 
#endif  // USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S2 || USE_ESP32_VARIANT_ESP32S3 ||
        // USE_ESP32_VARIANT_ESP32S31 || USE_ESP32_VARIANT_ESP32H4