remote_base.h

Go to the documentation of this file.

#pragma once
 
#include <concepts>
#include <utility>
#include <vector>
 
#include "esphome/components/binary_sensor/binary_sensor.h"
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/hal.h"
#include "esphome/core/helpers.h"
 
namespace esphome::remote_base {
 
enum ToleranceMode : uint8_t {
  TOLERANCE_MODE_PERCENTAGE = 0,
  TOLERANCE_MODE_TIME = 1,
};
 
using RawTimings = std::vector<int32_t>;
 
enum class BitOrder : uint8_t {
  BIT_ORDER_LSB_FIRST,
  BIT_ORDER_MSB_FIRST,
};
 
struct BitTimings {
  uint32_t bit_mark{0};
  uint32_t one_space;
  uint32_t zero_space;
  BitOrder bit_order{BitOrder::BIT_ORDER_LSB_FIRST};
  uint32_t one_mark{bit_mark};
  uint32_t zero_mark{bit_mark};
  bool space_first{false};
};
 
class RemoteTransmitData {
 public:
  void mark(uint32_t length) { this->data_.push_back(length); }
  void space(uint32_t length) { this->data_.push_back(-length); }
  void item(uint32_t mark, uint32_t space) {
    this->mark(mark);
    this->space(space);
  }
  void reserve(uint32_t len) { this->data_.reserve(len); }
  template<BitTimings T> void item_bytes(const uint8_t *bytes, size_t len) {
    static_assert(T.one_mark != 0 && T.zero_mark != 0, "set bit_mark, or one_mark and zero_mark");
    for (size_t i = 0; i < len; i++) {
      for (uint8_t bit = 0; bit < 8; bit++) {
        const uint8_t mask = T.bit_order == BitOrder::BIT_ORDER_MSB_FIRST ? (0x80 >> bit) : (1 << bit);
        const bool one = (bytes[i] & mask) != 0;
        if constexpr (T.space_first) {
          this->space(one ? T.one_space : T.zero_space);
          this->mark(one ? T.one_mark : T.zero_mark);
        } else {
          this->item(one ? T.one_mark : T.zero_mark, one ? T.one_space : T.zero_space);
        }
      }
    }
  }
  void set_carrier_frequency(uint32_t carrier_frequency) { this->carrier_frequency_ = carrier_frequency; }
  uint32_t get_carrier_frequency() const { return this->carrier_frequency_; }
  const RawTimings &get_data() const { return this->data_; }
  void set_data(const RawTimings &data) { this->data_ = data; }
  void set_data_from_packed_sint32(const uint8_t *data, size_t len, size_t count);
  bool set_data_from_base64url(const std::string &base64url);
  void reset() {
    this->data_.clear();
    this->carrier_frequency_ = 0;
  }
 
 protected:
  RawTimings data_{};
  uint32_t carrier_frequency_{0};
};
 
class RemoteReceiveData {
 public:
  explicit RemoteReceiveData(const RawTimings &data, uint32_t tolerance, ToleranceMode tolerance_mode)
      : data_(data), index_(0), tolerance_(tolerance), tolerance_mode_(tolerance_mode) {}
 
  const RawTimings &get_raw_data() const { return this->data_; }
  uint32_t get_index() const { return index_; }
  int32_t operator[](uint32_t index) const { return this->data_[index]; }
  int32_t size() const { return this->data_.size(); }
  bool is_valid(uint32_t offset = 0) const { return this->index_ + offset < this->data_.size(); }
  int32_t peek(uint32_t offset = 0) const { return this->data_[this->index_ + offset]; }
  bool peek_mark(uint32_t length, uint32_t offset = 0) const;
  bool peek_mark_at_least(uint32_t length, uint32_t offset = 0) const;
  bool peek_mark_at_most(uint32_t length, uint32_t offset = 0) const;
  bool peek_space(uint32_t length, uint32_t offset = 0) const;
  bool peek_space_at_least(uint32_t length, uint32_t offset = 0) const;
  bool peek_space_at_most(uint32_t length, uint32_t offset = 0) const;
  bool peek_item(uint32_t mark, uint32_t space, uint32_t offset = 0) const {
    return this->peek_space(space, offset + 1) && this->peek_mark(mark, offset);
  }
 
  bool expect_mark(uint32_t length);
  bool expect_space(uint32_t length);
  bool expect_item(uint32_t mark, uint32_t space);
  bool expect_pulse_with_gap(uint32_t mark, uint32_t space);
  template<BitTimings T> bool expect_bytes(uint8_t *out, size_t len) { return this->expect_bytes_<T, false>(out, len); }
  template<BitTimings T> bool expect_bytes_last_mark(uint8_t *out, size_t len) {
    static_assert(!T.space_first && T.one_mark != T.zero_mark, "the last bit must be told apart by its mark");
    return this->expect_bytes_<T, true>(out, len);
  }
  void advance(uint32_t amount = 1) { this->index_ += amount; }
  void reset() { this->index_ = 0; }
 
  void set_tolerance(uint32_t tolerance, ToleranceMode tolerance_mode) {
    this->tolerance_ = tolerance;
    this->tolerance_mode_ = tolerance_mode;
  }
  uint32_t get_tolerance() { return tolerance_; }
  ToleranceMode get_tolerance_mode() { return this->tolerance_mode_; }
 
 protected:
  template<BitTimings T, bool LAST_MARK> bool expect_bytes_(uint8_t *out, size_t len) {
    static_assert(T.one_mark != 0 && T.zero_mark != 0, "set bit_mark, or one_mark and zero_mark");
    for (size_t i = 0; i < len; i++) {
      uint8_t byte = 0;
      for (uint8_t bit = 0; bit < 8; bit++) {
        const uint8_t mask = T.bit_order == BitOrder::BIT_ORDER_MSB_FIRST ? (0x80 >> bit) : (1 << bit);
        if (LAST_MARK && i + 1 == len && bit == 7) {
          if (this->expect_mark(T.one_mark)) {
            byte |= mask;
          } else if (!this->expect_mark(T.zero_mark)) {
            return false;
          }
        } else if (this->expect_bit_<T>(T.one_mark, T.one_space)) {
          byte |= mask;
        } else if (!this->expect_bit_<T>(T.zero_mark, T.zero_space)) {
          return false;
        }
      }
      out[i] = byte;
    }
    return true;
  }
  template<BitTimings T> bool expect_bit_(uint32_t mark, uint32_t space) {
    if constexpr (T.space_first) {
      if (!this->peek_space(space) || !this->peek_mark(mark, 1))
        return false;
      this->advance(2);
      return true;
    } else {
      return this->expect_item(mark, space);
    }
  }
  int32_t lower_bound_(uint32_t length) const {
    if (this->tolerance_mode_ == TOLERANCE_MODE_TIME) {
      return int32_t(length - this->tolerance_);
    } else if (this->tolerance_mode_ == TOLERANCE_MODE_PERCENTAGE) {
      return int32_t(100 - this->tolerance_) * length / 100U;
    }
    return 0;
  }
  int32_t upper_bound_(uint32_t length) const {
    if (this->tolerance_mode_ == TOLERANCE_MODE_TIME) {
      return int32_t(length + this->tolerance_);
    } else if (this->tolerance_mode_ == TOLERANCE_MODE_PERCENTAGE) {
      return int32_t(100 + this->tolerance_) * length / 100U;
    }
    return 0;
  }
 
  const RawTimings &data_;
  uint32_t index_;
  uint32_t tolerance_;
  ToleranceMode tolerance_mode_;
};
 
class RemoteComponentBase {
 public:
  explicit RemoteComponentBase(InternalGPIOPin *pin) : pin_(pin) {};
 
 protected:
  InternalGPIOPin *pin_;
};
 
#ifdef USE_ESP32
#include <soc/soc_caps.h>
#if SOC_RMT_SUPPORTED
class RemoteRMTChannel {
 public:
  void set_clock_resolution(uint32_t clock_resolution) { this->clock_resolution_ = clock_resolution; }
  void set_rmt_symbols(uint32_t rmt_symbols) { this->rmt_symbols_ = rmt_symbols; }
 
 protected:
  uint32_t from_microseconds_(uint32_t us) {
    const uint32_t ticks_per_ten_us = this->clock_resolution_ / 100000u;
    return us * ticks_per_ten_us / 10;
  }
  uint32_t to_microseconds_(uint32_t ticks) {
    const uint32_t ticks_per_ten_us = this->clock_resolution_ / 100000u;
    return (ticks * 10) / ticks_per_ten_us;
  }
  RemoteComponentBase *remote_base_;
  uint32_t clock_resolution_{1000000};
  uint32_t rmt_symbols_;
};
#endif  // SOC_RMT_SUPPORTED
#endif  // USE_ESP32
 
class RemoteTransmitterBase;
 
#ifdef USE_IR_RF_TRANSMIT_COMPLETE
void ir_rf_transmit_complete(RemoteTransmitterBase *transmitter, uint16_t seq, bool sent);
#endif
// Protocol shapes, checked where a protocol is used so a missing method fails at the use site
// instead of deep inside a template body. Receive-only protocols such as RCSwitchBase decode
// without encoding.
template<typename T>
concept RemoteProtocolDecoder = requires(T proto, RemoteReceiveData src) {
  { proto.decode(src) } -> std::same_as<optional<typename T::ProtocolData>>;
};
template<typename T>
concept RemoteProtocolDumper =
    RemoteProtocolDecoder<T> && requires(T proto, const typename T::ProtocolData &data) { proto.dump(data); };
template<typename T>
concept RemoteProtocolEncoder =
    requires(T proto, RemoteTransmitData *dst, const typename T::ProtocolData &data) { proto.encode(dst, data); };
 
class RemoteTransmitterBase : public RemoteComponentBase {
 public:
  RemoteTransmitterBase(InternalGPIOPin *pin) : RemoteComponentBase(pin) {}
  class TransmitCall {
   public:
    TransmitCall(RemoteTransmitterBase *parent, uint16_t seq) : parent_(parent), seq_(seq) {}
    RemoteTransmitData *get_data() { return &this->parent_->temp_; }
    void set_send_times(uint32_t send_times) { send_times_ = send_times; }
    void set_send_wait(uint32_t send_wait) { send_wait_ = send_wait; }
    uint16_t get_seq() const { return this->seq_; }
    void perform() { this->parent_->send_(this->send_times_, this->send_wait_, this->seq_); }
 
   protected:
    RemoteTransmitterBase *parent_;
    uint32_t send_times_{1};
    uint32_t send_wait_{0};
    uint16_t seq_;
  };
 
  TransmitCall transmit();
  template<RemoteProtocolEncoder Protocol>
  void transmit(const typename Protocol::ProtocolData &data, uint32_t send_times = 1, uint32_t send_wait = 0) {
    this->transmit_encoded_(&encode_thunk<Protocol>, &data, send_times, send_wait);
  }
  template<RemoteProtocolEncoder Protocol> class ProtocolCall {
   public:
    explicit ProtocolCall(RemoteTransmitterBase *parent) : parent_(parent) {}
    void set_send_times(uint32_t send_times) { this->send_times_ = send_times; }
    void set_send_wait(uint32_t send_wait) { this->send_wait_ = send_wait; }
    void perform() { this->parent_->template transmit<Protocol>(this->data, this->send_times_, this->send_wait_); }
 
    typename Protocol::ProtocolData data{};
 
   protected:
    RemoteTransmitterBase *parent_;
    uint32_t send_times_{1};
    uint32_t send_wait_{0};
  };
  template<RemoteProtocolEncoder Protocol> ProtocolCall<Protocol> protocol_call() {
    return ProtocolCall<Protocol>(this);
  }
  template<RemoteProtocolEncoder Protocol> class EncodeCall : public TransmitCall {
   public:
    explicit EncodeCall(TransmitCall call) : TransmitCall(call) {}
    template<typename... Args> void encode(const Args &...args) { Protocol().encode(this->get_data(), args...); }
  };
  template<RemoteProtocolEncoder Protocol> EncodeCall<Protocol> encode_call() {
    return EncodeCall<Protocol>(this->transmit());
  }
 
 protected:
  using EncodeFn = void (*)(RemoteTransmitData *dst, const void *data);
  // One out-of-line send path, so each transmit<P>() call site only fills its data.
  void transmit_encoded_(EncodeFn encode, const void *data, uint32_t send_times, uint32_t send_wait);
  template<RemoteProtocolEncoder Protocol> static void encode_thunk(RemoteTransmitData *dst, const void *data) {
    Protocol().encode(dst, *static_cast<const typename Protocol::ProtocolData *>(data));
  }
  void send_(uint32_t send_times, uint32_t send_wait, uint16_t seq);
  virtual void send_internal(uint32_t send_times, uint32_t send_wait) = 0;
  virtual void flush_pending_completion() {}
  void send_single_() { this->send_(1, 0, this->take_seq_()); }
#ifdef USE_IR_RF_TRANSMIT_COMPLETE
  void notify_complete_(bool sent) { ir_rf_transmit_complete(this, this->current_seq_, sent); }
  uint16_t take_seq_() { return ++this->next_seq_; }
 
  uint16_t next_seq_{0};
  uint16_t current_seq_{0};
#else
  // seq tracking only exists for the API completion reply
  void notify_complete_(bool /*sent*/) {}
  static uint16_t take_seq_() { return 0; }
#endif
 
  RemoteTransmitData temp_;
};
 
class RemoteReceiverListener {
 public:
  virtual bool on_receive(RemoteReceiveData data) = 0;
};
 
class RemoteReceiverDumperBase {
 public:
  virtual bool dump(RemoteReceiveData src) = 0;
  virtual bool is_secondary() { return false; }
};
 
class RemoteReceiverBase : public RemoteComponentBase {
 public:
  RemoteReceiverBase(InternalGPIOPin *pin) : RemoteComponentBase(pin) {}
  // Slots are counted at code generation; without one the call fails at compile time with the same message
  // the runtime check logs
#ifdef REMOTE_BASE_LISTENER_COUNT
  void register_listener(RemoteReceiverListener *listener);
#else
  template<typename T> void register_listener(T *) {
    static_assert(sizeof(T) == 0, "No listener slot: register it from to_code() with remote_base.add_listener");
  }
#endif
#ifdef REMOTE_BASE_DUMPER_COUNT
  void register_dumper(RemoteReceiverDumperBase *dumper);
#else
  template<typename T> void register_dumper(T *) {
    static_assert(sizeof(T) == 0, "No dumper slot: register it from to_code() with remote_base.add_dumper");
  }
#endif
  void set_tolerance(uint32_t tolerance, ToleranceMode tolerance_mode) {
    this->tolerance_ = tolerance;
    this->tolerance_mode_ = tolerance_mode;
  }
 
 protected:
  void call_listeners_dumpers_();
 
#ifdef REMOTE_BASE_LISTENER_COUNT
  StaticVector<RemoteReceiverListener *, REMOTE_BASE_LISTENER_COUNT> listeners_;
#endif
#ifdef REMOTE_BASE_DUMPER_COUNT
  StaticVector<RemoteReceiverDumperBase *, REMOTE_BASE_DUMPER_COUNT> dumpers_;
  RemoteReceiverDumperBase *secondary_dumper_{nullptr};  // runs only when no primary dumper matched
#endif
  RawTimings temp_;
  uint32_t tolerance_{25};
  ToleranceMode tolerance_mode_{TOLERANCE_MODE_PERCENTAGE};
};
 
class RemoteReceiverBinarySensorBase : public binary_sensor::BinarySensorInitiallyOff,
                                       public Component,
                                       public RemoteReceiverListener {
 public:
  explicit RemoteReceiverBinarySensorBase() {}
  void dump_config() override;
  virtual bool matches(RemoteReceiveData src) = 0;
  bool on_receive(RemoteReceiveData src) override;
};
 
/* TEMPLATES */
 
// Protocols are used only through their concrete type (see the RemoteProtocol* concepts); encode/decode/dump
// stay non-virtual so unused ones link out
template<typename T> class RemoteProtocol {
 public:
  using ProtocolData = T;
};
 
template<RemoteProtocolDecoder T> class RemoteReceiverBinarySensor : public RemoteReceiverBinarySensorBase {
 public:
  RemoteReceiverBinarySensor() : RemoteReceiverBinarySensorBase() {}
 
 protected:
  bool matches(RemoteReceiveData src) override {
    auto proto = T();
    auto res = proto.decode(src);
    return res.has_value() && *res == this->data_;
  }
 
 public:
  void set_data(T::ProtocolData data) { data_ = data; }
 
 protected:
  T::ProtocolData data_;
};
 
template<RemoteProtocolDecoder T>
class RemoteReceiverTrigger final : public Trigger<typename T::ProtocolData>, public RemoteReceiverListener {
 protected:
  bool on_receive(RemoteReceiveData src) override {
    auto proto = T();
    auto res = proto.decode(src);
    if (res.has_value()) {
      this->trigger(*res);
      return true;
    }
    return false;
  }
};
 
class RemoteTransmittable {
 public:
  RemoteTransmittable() {}
  RemoteTransmittable(RemoteTransmitterBase *transmitter) : transmitter_(transmitter) {}
  void set_transmitter(RemoteTransmitterBase *transmitter) { this->transmitter_ = transmitter; }
 
 protected:
  template<RemoteProtocolEncoder Protocol>
  void transmit_(const typename Protocol::ProtocolData &data, uint32_t send_times = 1, uint32_t send_wait = 0) {
    this->transmitter_->transmit<Protocol>(data, send_times, send_wait);
  }
  RemoteTransmitterBase *transmitter_;
};
 
template<typename... Ts> class RemoteTransmitterActionBase : public RemoteTransmittable, public Action<Ts...> {
  TEMPLATABLE_VALUE(uint32_t, send_times)
  TEMPLATABLE_VALUE(uint32_t, send_wait)
 
 protected:
  void play(const Ts &...x) override {
    auto call = this->transmitter_->transmit();
    this->encode(call.get_data(), x...);
    call.set_send_times(this->send_times_.value_or(x..., 1));
    call.set_send_wait(this->send_wait_.value_or(x..., 0));
    call.perform();
  }
  virtual void encode(RemoteTransmitData *dst, Ts... x) = 0;
};
 
template<RemoteProtocolDumper T> class RemoteReceiverDumper : public RemoteReceiverDumperBase {
 public:
  bool dump(RemoteReceiveData src) override {
    auto proto = T();
    auto decoded = proto.decode(src);
    if (!decoded.has_value())
      return false;
    proto.dump(*decoded);
    return true;
  }
};
 
#define DECLARE_REMOTE_PROTOCOL_(prefix) \
  using prefix##BinarySensor = RemoteReceiverBinarySensor<prefix##Protocol>; \
  using prefix##Trigger = RemoteReceiverTrigger<prefix##Protocol>; \
  using prefix##Dumper = RemoteReceiverDumper<prefix##Protocol>;
#define DECLARE_REMOTE_PROTOCOL(prefix) DECLARE_REMOTE_PROTOCOL_(prefix)
 
}  // namespace esphome::remote_base