pd.cpp

Go to the documentation of this file.

#include "pd.h"
 
#include <cstring>
 
#include "esphome/core/hal.h"
#include "esphome/core/log.h"
 
namespace esphome::fusb302b {
 
ESPHOME_LOG_TAG(TAG, "fusb302b.pd");
 
static constexpr uint32_t AMS_TIMEOUT_MS = 2000;
// tSinkRequest: delay before repeating a request that the source answered with Wait
static constexpr uint32_t SINK_REQUEST_MS = 100;
static constexpr uint8_t MAX_WAIT_RETRIES = 10;
 
// USB PD 6.4.1.3.1 Sink Fixed Supply Power Data Object flags; only the first (5 V) object carries them
static constexpr uint32_t SINK_PDO_HIGHER_CAPABILITY = 1u << 28;
static constexpr uint32_t SINK_PDO_USB_COMMS_CAPABLE = 1u << 26;
// Operational current advertised for every sink object: 3 A (300 x 10 mA)
static constexpr uint16_t SINK_PDO_CURRENT = 300;
 
// USB PD 6.4.1.2.3 Source Fixed Supply Power Data Object; other PDO types only report their type
static PdContract parse_pdo(uint32_t pdo) {
  PdContract info{};
  info.type = static_cast<PdPdoType>(pdo >> 30);
  if (info.type == PD_PDO_TYPE_FIXED_SUPPLY) {
    info.max_v = (pdo >> 10) & 0x3FF;
    info.max_i = pdo & 0x3FF;
  }
  return info;
}
 
// USB PD 6.4.1.3.1 Sink Fixed Supply Power Data Object; voltage in 50 mV units, current in 10 mA units
static constexpr uint32_t sink_fixed_pdo(uint16_t voltage, uint16_t current) {
  return (static_cast<uint32_t>(PD_PDO_TYPE_FIXED_SUPPLY) << 30) | (static_cast<uint32_t>(voltage & 0x3FF) << 10) |
         (current & 0x3FF);
}
 
void PdMsg::set_header(uint16_t header) {
  this->type = header & 0x1F;
  this->spec_rev = static_cast<PdSpecRevision>((header >> 6) & 0x3);
  this->id = (header >> 9) & 0x7;
  this->num_of_obj = (header >> 12) & 0x7;
  this->extended = (header >> 15) & 0x1;
}
 
uint16_t PdMsg::get_coded_header() const {
  // Data role UFP (bit 5 = 0), power role sink (bit 8 = 0)
  return static_cast<uint16_t>(this->type & 0x1F) | (static_cast<uint16_t>(this->spec_rev) << 6) |
         (static_cast<uint16_t>(this->id & 0x7) << 9) | (static_cast<uint16_t>(this->num_of_obj & 0x7) << 12) |
         (static_cast<uint16_t>(this->extended) << 15);
}
 
PdMsg PowerDelivery::make_control_msg_(PdControlMsgType type) const {
  PdMsg msg;
  msg.type = type;
  msg.id = this->msg_counter_ % 8;
  return msg;
}
 
PdMsg PowerDelivery::make_data_msg_(PdDataMsgType type, const uint32_t *objects, uint8_t len) const {
  PdMsg msg;
  msg.type = type;
  msg.id = this->msg_counter_ % 8;
  msg.num_of_obj = len;
  memcpy(msg.data_objects, objects, len * sizeof(uint32_t));
  return msg;
}
 
void PowerDelivery::reset_protocol_() {
  this->last_received_msg_id_ = 255;
  this->msg_counter_ = 0;
  this->active_ams_ = false;
  this->ps_rdy_expected_ = false;
  this->retry_request_pending_ = false;
  this->wait_retries_ = 0;
}
 
void PowerDelivery::set_state_(PdState state) {
  if (this->state_.exchange(state) != state)
    this->on_state_changed();
}
 
void PowerDelivery::set_contract_(const PdContract &contract) {
  this->accepted_contract_ = contract;
  const uint32_t packed = PackedContract::from(contract).value;
  if (this->contract_.exchange(packed) != packed)
    this->on_state_changed();
}
 
void PowerDelivery::clear_contract_() {
  this->accepted_contract_ = {};
  if (this->contract_.exchange(0) != 0)
    this->on_state_changed();
}
 
void PowerDelivery::set_state_and_contract_(PdState state, const PdContract &contract) {
  this->accepted_contract_ = contract;
  const uint32_t packed = PackedContract::from(contract).value;
  // The contract is stored first, so a reader that sees the new state also sees the new contract
  const bool contract_changed = this->contract_.exchange(packed) != packed;
  const bool state_changed = this->state_.exchange(state) != state;
  if (contract_changed || state_changed)
    this->on_state_changed();
}
 
void PowerDelivery::set_ams_(bool active) {
  this->active_ams_ = active;
  // A new sequence has no accepted request yet, and an ended one can no longer complete
  this->ps_rdy_expected_ = false;
  if (active)
    this->ams_start_ = millis();
}
 
bool PowerDelivery::check_ams_() {
  if (this->active_ams_ && millis() - this->ams_start_ > AMS_TIMEOUT_MS) {
    this->set_ams_(false);
    // Every sequence carries a request. In TRANSITION, check_transition_timeout_() handles the missing PS_RDY.
    if (this->state_ != PdState::PD_STATE_TRANSITION) {
      ESP_LOGW(TAG, "Source did not complete the request in time");
      this->request_failed_();
    }
  }
  return this->active_ams_;
}
 
void PowerDelivery::check_request_retry_() {
  if (!this->retry_request_pending_ || millis() - this->wait_received_ms_ < SINK_REQUEST_MS)
    return;
  if (this->send_request_()) {
    this->retry_request_pending_ = false;
  } else if (this->wait_retries_ < MAX_WAIT_RETRIES) {
    // Try again after another tSinkRequest; failed attempts count against the same limit as Wait replies
    this->wait_retries_++;
    this->wait_received_ms_ = millis();
  } else {
    ESP_LOGW(TAG, "Giving up repeating the request");
    this->retry_request_pending_ = false;
    this->request_failed_();
  }
}
 
bool PowerDelivery::send_request_() {
  this->set_ams_(true);
  if (this->send_message(this->make_data_msg_(PD_DATA_REQUEST, &this->last_rdo_, 1)))
    return true;
  ESP_LOGW(TAG, "Sending the request failed");
  this->set_ams_(false);
  return false;
}
 
void PowerDelivery::request_failed_() {
  // A contract already in place stays valid. Without one, report that negotiation is over at default power.
  if (this->state_ == PdState::PD_STATE_DEFAULT_CONTRACT)
    this->set_state_(PdState::PD_STATE_PD_TIMEOUT);
  this->on_request_failed();
}
 
void PowerDelivery::check_transition_timeout_() {
  // The AMS that sent the request only ends on PS_RDY, so an ended AMS while in transition means a timeout
  if (this->state_ != PdState::PD_STATE_TRANSITION || this->check_ams_())
    return;
  ESP_LOGW(TAG, "Source did not report the new supply ready, falling back to default power");
  this->set_state_and_contract_(PdState::PD_STATE_DEFAULT_CONTRACT, DEFAULT_CONTRACT);
  this->on_transition_timeout();
}
 
void PowerDelivery::handle_transmit_failed_() {
  // USB PD 6.12.2.2: the counter also moves on after a failed transmission. The source may have received the
  // message and only its GoodCRC was lost, so reusing the MessageID would make it drop the next one as a repeat.
  ESP_LOGD(TAG, "Message %u not acknowledged", this->msg_counter_ % 8);
  this->msg_counter_++;
}
 
void PowerDelivery::handle_message_(const PdMsg &msg) {
  if (msg.num_of_obj == 0 && msg.type == PD_CNTRL_GOODCRC) {
    // A GoodCRC carries the MessageID it acknowledges; a duplicate or stray one must not advance the counter
    if (msg.id != this->msg_counter_ % 8) {
      ESP_LOGD(TAG, "Ignoring GoodCRC for MessageID %u, expected %u", msg.id, this->msg_counter_ % 8);
      return;
    }
    // Our last message was received, so the next one gets a new MessageID
    this->msg_counter_++;
    return;
  }
  // Soft_Reset always has MessageID 0, so it must not be dropped as a retransmission of the last message
  if (msg.num_of_obj == 0 && msg.type == PD_CNTRL_SOFT_RESET) {
    this->handle_soft_reset_(msg);
    return;
  }
  // Retransmissions repeat the MessageID of a message that was already handled
  if (msg.id == this->last_received_msg_id_)
    return;
  this->last_received_msg_id_ = msg.id;
 
  if (msg.num_of_obj == 0) {
    this->handle_control_message_(msg);
  } else {
    this->handle_data_message_(msg);
  }
}
 
void PowerDelivery::handle_data_message_(const PdMsg &msg) {
  if (msg.extended || msg.type != PD_DATA_SOURCE_CAP) {
    // BIST and Vendor_Defined messages must not be answered with Reject, so unsupported data messages are ignored
    ESP_LOGV(TAG, "Ignoring data message type %u%s", msg.type,
             msg.extended ? LOG_STR_LITERAL(" (extended)") : LOG_STR_LITERAL(""));
    return;
  }
  this->on_source_caps_received();
  this->respond_to_source_caps_(msg);
}
 
void PowerDelivery::handle_control_message_(const PdMsg &msg) {
  switch (msg.type) {
    case PD_CNTRL_ACCEPT:
      if (!this->check_ams_()) {
        ESP_LOGD(TAG, "Ignoring Accept outside a request");
        break;
      }
      this->ps_rdy_expected_ = true;
      if (this->requested_contract_ != this->accepted_contract_)
        this->set_state_and_contract_(PdState::PD_STATE_TRANSITION, this->requested_contract_);
      break;
    case PD_CNTRL_PS_RDY:
      // check_ams_() first, so a PS_RDY that arrives after the sequence timed out is ignored too
      if (!this->check_ams_() || !this->ps_rdy_expected_) {
        ESP_LOGD(TAG, "Ignoring PS_RDY without an accepted request");
        break;
      }
      this->set_ams_(false);
      this->set_state_(PdState::PD_STATE_EXPLICIT_CONTRACT);
      break;
    case PD_CNTRL_REJECT:
      if (!this->check_ams_()) {
        ESP_LOGD(TAG, "Ignoring Reject outside a request");
        break;
      }
      ESP_LOGW(TAG, "Source rejected the request");
      this->set_ams_(false);
      this->request_failed_();
      break;
    case PD_CNTRL_WAIT:
      if (!this->check_ams_()) {
        ESP_LOGD(TAG, "Ignoring Wait outside a request");
        break;
      }
      this->set_ams_(false);
      if (this->wait_retries_ < MAX_WAIT_RETRIES) {
        ESP_LOGD(TAG, "Source asked to wait, repeating the request");
        this->wait_retries_++;
        this->retry_request_pending_ = true;
        this->wait_received_ms_ = millis();
      } else {
        ESP_LOGW(TAG, "Source kept answering Wait, giving up");
        this->request_failed_();
      }
      break;
    case PD_CNTRL_PING:
    case PD_CNTRL_NOT_SUPPORTED:
      break;
    case PD_CNTRL_GET_SINK_CAP: {
      // 5 V first, then the requested voltage. Higher Capability tells the source that 5 V is not enough for
      // full operation.
      const uint16_t request_v = this->request_voltage_ * 20;  // 50 mV units
      uint32_t pdos[2];
      uint8_t count = 0;
      pdos[count++] = sink_fixed_pdo(100, SINK_PDO_CURRENT) | SINK_PDO_USB_COMMS_CAPABLE |
                      (request_v > 100 ? SINK_PDO_HIGHER_CAPABILITY : 0);
      if (request_v > 100)
        pdos[count++] = sink_fixed_pdo(request_v, SINK_PDO_CURRENT);
      this->send_message(this->make_data_msg_(PD_DATA_SINK_CAP, pdos, count));
      break;
    }
    default:
      // Messages are sent as PD 2.0, which has no Not_Supported message
      this->send_message(this->make_control_msg_(PD_CNTRL_REJECT));
      break;
  }
}
 
void PowerDelivery::handle_soft_reset_(const PdMsg &msg) {
  this->reset_protocol_();
  this->last_received_msg_id_ = msg.id;
  // If this fails the source escalates to a hard reset. The hook still runs, so the PHY starts waiting for source
  // capabilities and recovers on its own if neither follows.
  if (!this->send_message(this->make_control_msg_(PD_CNTRL_ACCEPT))) {
    ESP_LOGW(TAG, "Accepting the soft reset failed");
  }
  // A soft reset keeps the power level, but the outcome of a transition in progress is unknown
  if (this->state_ == PdState::PD_STATE_TRANSITION)
    this->set_state_and_contract_(PdState::PD_STATE_DEFAULT_CONTRACT, DEFAULT_CONTRACT);
  this->on_soft_reset_received();
}
 
void PowerDelivery::respond_to_source_caps_(const PdMsg &msg) {
  // Pick the highest fixed supply PDO that does not exceed the requested voltage.
  // The first PDO is always the 5 V fixed supply.
  const uint16_t request_v = this->request_voltage_ * 20;  // 50 mV units
  PdContract selected{};
  uint8_t position = 0;  // 1-based object position, 0 = none
  for (uint8_t idx = 0; idx < msg.num_of_obj; idx++) {
    PdContract info = parse_pdo(msg.data_objects[idx]);
    if (info.type != PD_PDO_TYPE_FIXED_SUPPLY)
      continue;
    if (position == 0 || (info.max_v <= request_v && info.max_v > selected.max_v)) {
      selected = info;
      position = idx + 1;
    }
  }
 
  // USB PD 6.4.2 Request Data Object: no USB suspend (bit 24), USB communications capable (bit 25)
  uint32_t rdo = (1u << 24) | (1u << 25);
  if (position == 0) {
    ESP_LOGW(TAG, "No usable PDO in source capabilities, requesting 5 V");
    // Object 1 (5 V fixed supply), 300 mA maximum, 100 mA operating current
    selected = PdContract{PD_PDO_TYPE_FIXED_SUPPLY, 100, 30};
    position = 1;
    rdo |= (30u << 0) | (10u << 10);
  } else {
    // Request the full current the source offers
    const uint32_t current = selected.max_i;
    rdo |= (current << 0) | (current << 10);
  }
  rdo |= static_cast<uint32_t>(position) << 28;
  ESP_LOGD(TAG, "Requesting PDO %u: %.2f V", position, selected.max_v * 0.05f);
  this->requested_contract_ = selected;
  this->last_rdo_ = rdo;
  this->retry_request_pending_ = false;
  this->wait_retries_ = 0;
  // A repeat would come too late: the source resets if it gets no Request within tSenderResponse (24-30 ms)
  if (!this->send_request_())
    this->request_failed_();
}
 
}  // namespace esphome::fusb302b