serial_proxy.h

Go to the documentation of this file.

#pragma once
 
// WARNING: This component is EXPERIMENTAL. The API may change at any time
// without following the normal breaking changes policy. Use at your own risk.
// Once the API is considered stable, this warning will be removed.
 
#include "esphome/core/defines.h"
 
#ifdef USE_SERIAL_PROXY
 
#include "esphome/core/component.h"
#include "esphome/core/hal.h"
#include "esphome/components/uart/uart.h"
 
// Include api_pb2.h only when the API is enabled. The full include is needed
// to hold SerialProxyDataReceived by value as a pre-allocated member.
// Guarding prevents pulling conflicting Zephyr logging macro names into
// translation units that include this header without USE_API defined.
#ifdef USE_API
#include "esphome/components/api/api_pb2.h"
#endif
 
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
namespace esphome::usb_uart {
class USBUartChannel;
}  // namespace esphome::usb_uart
namespace esphome::usb_host {
struct UsbDeviceInfo;
}  // namespace esphome::usb_host
#endif
 
#ifdef USE_SERIAL_PROXY_HOST_UART
namespace esphome::uart {
class HostUartComponent;
}  // namespace esphome::uart
#endif
 
// Forward-declare types needed outside the USE_API guard.
namespace esphome::api {
class APIConnection;
namespace enums {
enum SerialProxyPortType : uint32_t;
enum SerialProxyRequestType : uint32_t;
enum SerialProxyMode : uint32_t;
}  // namespace enums
}  // namespace esphome::api
 
namespace esphome::serial_proxy {
 
enum SerialProxyLineStateFlag : uint32_t {
  SERIAL_PROXY_LINE_STATE_FLAG_RTS = 1 << 0,  
  SERIAL_PROXY_LINE_STATE_FLAG_DTR = 1 << 1,  
};
 
enum class SerialProxyResult : uint8_t {
  SERIAL_PROXY_RESULT_OK,                
  SERIAL_PROXY_RESULT_ASSUMED_SUCCESS,   
  SERIAL_PROXY_RESULT_PORT_IN_USE,       
  SERIAL_PROXY_RESULT_INVALID_ARGUMENT,  
  SERIAL_PROXY_RESULT_ERROR,             
  SERIAL_PROXY_RESULT_TIMEOUT,           
  SERIAL_PROXY_RESULT_NOT_SUPPORTED,     
};
 
inline constexpr size_t SERIAL_PROXY_MAX_READ_SIZE = 256;
 
inline constexpr uint32_t SERIAL_PROXY_MAX_WRITE_STALL_MS = 1000;
 
#ifdef USE_SERIAL_PROXY_TAP
class SerialProxyTap {
 public:
  virtual void on_device_rx(const uint8_t *data, size_t len) = 0;
 
  virtual void on_client_tx(const uint8_t *data, size_t len) = 0;
 
  virtual bool tap_needs_port() const = 0;
 
  virtual void on_protocol_enabled() = 0;
 
  virtual void on_protocol_disabled() = 0;
 
  virtual void on_device_disconnected() = 0;
};
#endif
 
class SerialProxy final : public uart::UARTDevice, public Component {
 public:
  void setup() override;
  void loop() override;
  void dump_config() override;
  float get_setup_priority() const override { return setup_priority::AFTER_CONNECTION; }
 
  uint32_t get_instance_index() const { return this->instance_index_; }
 
  void set_instance_index(uint32_t index) { this->instance_index_ = index; }
 
  void set_name(const char *name) { this->name_ = name; }
 
  const char *get_name() const { return this->name_; }
 
  void set_port_type(api::enums::SerialProxyPortType port_type) { this->port_type_ = port_type; }
 
  api::enums::SerialProxyPortType get_port_type() const { return this->port_type_; }
 
  SerialProxyResult set_mode_from_client(api::APIConnection *api_connection, api::enums::SerialProxyMode mode);
 
  SerialProxyResult configure(api::APIConnection *api_connection, uint32_t baudrate, bool flow_control, uint8_t parity,
                              uint8_t stop_bits, uint8_t data_size);
 
  api::APIConnection *get_api_connection() { return this->api_connection_; }
 
  SerialProxyResult serial_proxy_request(api::APIConnection *api_connection, api::enums::SerialProxyRequestType type);
 
  void write_from_client(api::APIConnection *api_connection, const uint8_t *data, size_t len);
 
  SerialProxyResult set_modem_pins(api::APIConnection *api_connection, uint32_t line_states);
 
  uint32_t get_modem_pins() const;
 
  uint32_t get_configured_modem_pins() const {
    const bool uart_lines = this->with_modem_uart_([](auto *) {});
    return (this->rts_pin_ != nullptr || uart_lines ? static_cast<uint32_t>(SERIAL_PROXY_LINE_STATE_FLAG_RTS) : 0u) |
           (this->dtr_pin_ != nullptr || uart_lines ? static_cast<uint32_t>(SERIAL_PROXY_LINE_STATE_FLAG_DTR) : 0u);
  }
 
  SerialProxyResult flush_port(api::APIConnection *api_connection);
 
  void set_rts_pin(GPIOPin *pin) { this->rts_pin_ = pin; }
 
  void set_dtr_pin(GPIOPin *pin) { this->dtr_pin_ = pin; }
 
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  void set_usb_channel(usb_uart::USBUartChannel *channel) { this->usb_channel_ = channel; }
#endif
 
#ifdef USE_SERIAL_PROXY_HOST_UART
  void set_host_uart(uart::HostUartComponent *host_uart) { this->host_uart_ = host_uart; }
#endif
 
#ifdef USE_API
  void send_identity(api::APIConnection *api_connection);
#endif
 
#ifdef USE_SERIAL_PROXY_TAP
  void set_tap(SerialProxyTap *tap) { this->tap_ = tap; }
 
  bool write_from_tap(const uint8_t *data, size_t len) {
    if (!this->tap_observing_()) {
      return false;
    }
    this->write_array(data, len);
    return true;
  }
 
  bool tap_is_observed() const { return this->tap_observing_(); }
 
  void tap_request_port() { this->enable_loop(); }
 
  bool is_device_connected() const { return this->parent_->is_connected(); }
 
  void tap_pump();
#endif
 
 protected:
#ifdef USE_API
  void read_and_send_(size_t available);
 
  bool is_subscriber_(api::APIConnection *api_connection) const { return this->api_connection_ == api_connection; }
#endif
 
  template<typename F> bool with_modem_uart_(F &&f) const {
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
    if (this->usb_channel_ != nullptr) {
      f(this->usb_channel_);
      return true;
    }
#endif
#ifdef USE_SERIAL_PROXY_HOST_UART
    if (this->host_uart_ != nullptr) {
      f(this->host_uart_);
      return true;
    }
#endif
    return false;
  }
 
  uint32_t wire_time_ms_(size_t bytes) const;
 
#ifdef USE_SERIAL_PROXY_TAP
  void reset_mode_();
#else
  void reset_mode_() {}
#endif
 
#ifdef USE_SERIAL_PROXY_TAP
  bool tap_observing_() const;
#endif
 
#ifdef USE_API
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  using IdentityScratch = usb_host::UsbDeviceInfo;
#else
  struct IdentityScratch {};
#endif
  void fill_identity_(IdentityScratch &scratch, api::SerialProxyIdentity &msg) const;
#endif
 
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  void on_usb_connection_changed_(bool connected);
#endif
 
  uint32_t instance_index_{0};
 
  static uint32_t stall_loop_time;
  static uint32_t stall_spent_ms;
 
  api::APIConnection *api_connection_{nullptr};
 
#ifdef USE_API
  api::SerialProxyDataReceived outgoing_msg_;
#endif
 
  const char *name_{nullptr};
 
  api::enums::SerialProxyPortType port_type_{};
 
#ifdef USE_SERIAL_PROXY_TAP
  api::enums::SerialProxyMode mode_{};
#endif
 
  GPIOPin *rts_pin_{nullptr};
  GPIOPin *dtr_pin_{nullptr};
 
  bool rts_state_{false};
  bool dtr_state_{false};
 
  bool trim_warned_{false};
 
#ifdef USE_SERIAL_PROXY_TAP
  SerialProxyTap *tap_{nullptr};
#endif
 
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  usb_uart::USBUartChannel *usb_channel_{nullptr};
#endif
 
#ifdef USE_SERIAL_PROXY_HOST_UART
  uart::HostUartComponent *host_uart_{nullptr};
#endif
};
 
}  // namespace esphome::serial_proxy
 
#endif  // USE_SERIAL_PROXY