sendspin_hub.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/defines.h"
 
#ifdef USE_ESP_IDF
 
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/helpers.h"
#include "esphome/core/preferences.h"
#include "esphome/core/string_ref.h"
#include "esphome/core/version.h"
 
#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
#include "esphome/components/mdns/mdns_component.h"
#endif
 
#include <sendspin/client.h>
#include <sendspin/config.h>
#include <sendspin/types.h>
 
#ifdef USE_SENDSPIN_ARTWORK
#include <sendspin/artwork_role.h>
#endif
#ifdef USE_SENDSPIN_CONTROLLER
#include <sendspin/controller_role.h>
#endif
#ifdef USE_SENDSPIN_METADATA
#include <sendspin/metadata_role.h>
#endif
#ifdef USE_SENDSPIN_PLAYER
#include <sendspin/player_role.h>
#endif
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
namespace esphome::sendspin_ {
 
namespace sendspin_priority {
// AFTER_WIFI so the hub runs after the wifi/ethernet drivers are up and we can read the active
// interface's MAC address for the device info.
inline constexpr float HUB = esphome::setup_priority::AFTER_WIFI;
inline constexpr float CHILD = HUB - 1.0f;
}  // namespace sendspin_priority
 
// PREFERENCE KEYS: each library persistence key has its own preference, hashed from "sendspin_" + name. Renaming
// one erases it.
 
inline constexpr size_t SENDSPIN_RECORD_SLOTS = sendspin::SendspinClientConfig::DEFAULT_MAX_PAIRING_RECORDS;
 
enum SendspinFeature : uint32_t {
  SENDSPIN_FEATURE_PAIRING_TOKEN = 1 << 0,
};
 
class SendspinHub final : public Component,
#ifdef USE_SENDSPIN_ARTWORK
                          public sendspin::ArtworkRoleListener,
#endif
#ifdef USE_SENDSPIN_CONTROLLER
                          public sendspin::ControllerRoleListener,
#endif
#ifdef USE_SENDSPIN_METADATA
                          public sendspin::MetadataRoleListener,
#endif
                          public sendspin::SendspinClientListener,
                          public sendspin::SendspinNetworkProvider,
                          public sendspin::SendspinPersistenceProvider {
 public:
  SendspinHub();
 
  float get_setup_priority() const override { return sendspin_priority::HUB; }
  void setup() override;
  void loop() override;
  void on_shutdown() override;
  void dump_config() override;
 
  void connect_to_server(const std::string &url);
 
  void disconnect_from_server(sendspin::SendspinGoodbyeReason reason);
 
  void leave_group();
 
  void confirm_pairing_window();
 
  void cancel_pairing_window();
 
  // --- Configuration setters (called from codegen) ---
 
  template<typename F> void add_group_update_callback(F &&callback) {
    this->group_update_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_on_open_pairing_window_callback(F &&callback) {
    this->open_pairing_window_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_on_close_pairing_window_callback(F &&callback) {
    this->close_pairing_window_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_on_display_pairing_code_callback(F &&callback) {
    this->display_pairing_code_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_on_clear_pairing_code_callback(F &&callback) {
    this->clear_pairing_code_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_on_pairing_succeeded_callback(F &&callback) {
    this->pairing_succeeded_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_on_pairing_failed_callback(F &&callback) {
    this->pairing_failed_callbacks_.add(std::forward<F>(callback));
  }
 
  void set_task_stack_in_psram(bool task_stack_in_psram) { this->task_stack_in_psram_ = task_stack_in_psram; }
 
  void set_enabled(bool enabled);
 
  void set_unpaired_access_enabled(bool enabled);
 
  bool is_client_running() const { return this->client_ != nullptr && this->client_->is_started(); }
 
  bool is_disabled() const { return this->enabled_.has_value() && !this->enabled_.value(); }
 
  uint32_t get_feature_flags() const { return SENDSPIN_FEATURE_PAIRING_TOKEN; }
 
  std::optional<std::string> get_pairing_token() const;
 
  StringRef get_client_id() const;
 
  void set_manufacturer(const char *manufacturer) { this->manufacturer_ = manufacturer; }
  void set_model(const char *model) { this->model_ = model; }
  void set_firmware_version(const char *firmware_version) { this->firmware_version_ = firmware_version; }
 
#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
  void set_mdns(mdns::MDNSComponent *mdns) { this->mdns_ = mdns; }
#endif
 
  void set_static_pairing_code(const char *code) { this->static_pairing_code_ = code; }
 
  void set_pairing_code_display_supported(bool supported) { this->pairing_code_display_supported_ = supported; }
 
  // --- Sendspin role specific methods ---
 
#ifdef USE_SENDSPIN_ARTWORK
  void set_artwork_config(const sendspin::ArtworkRoleConfig &config) { this->artwork_config_ = config; }
 
  void artwork_frame_done(uint8_t slot);
 
  template<typename F> void add_image_decode_callback(F &&callback) {
    this->artwork_image_decode_callbacks_.add(std::forward<F>(callback));
  }
  template<typename F> void add_image_display_callback(F &&callback) {
    this->artwork_image_display_callbacks_.add(std::forward<F>(callback));
  }
  template<typename F> void add_image_clear_callback(F &&callback) {
    this->artwork_image_clear_callbacks_.add(std::forward<F>(callback));
  }
#endif
 
#ifdef USE_SENDSPIN_CONTROLLER
  void send_client_command(sendspin::SendspinControllerCommand command, std::optional<uint8_t> volume = std::nullopt,
                           std::optional<bool> mute = std::nullopt);
 
  void switch_client();
 
  template<typename F> void add_controller_state_callback(F &&callback) {
    this->controller_state_callbacks_.add(std::forward<F>(callback));
  }
 
  template<typename F> void add_controller_state_clear_callback(F &&callback) {
    this->controller_state_clear_callbacks_.add(std::forward<F>(callback));
  }
#endif
 
#ifdef USE_SENDSPIN_METADATA
  template<typename F> void add_metadata_update_callback(F &&callback) {
    this->metadata_update_callbacks_.add(std::forward<F>(callback));
  }
 
  uint32_t get_track_progress_ms() const;
#endif
 
#ifdef USE_SENDSPIN_PLAYER
  void set_listener(sendspin::PlayerRoleListener *listener) { this->player_listener_ = listener; }
  void set_player_config(const sendspin::PlayerRoleConfig &config) { this->player_config_ = config; }
 
  sendspin::PlayerRole *get_player_role();
#endif
 
 protected:
  sendspin::SendspinClientConfig build_client_config_();
 
  std::pair<ESPPreferenceObject *, size_t> pref_for_key_(const std::string &key);
 
  const char *get_product_name_() const;
 
  const char *pairing_code_method_() const;
 
  static const char *get_mac_address_into_buffer(std::span<char, MAC_ADDRESS_PRETTY_BUFFER_SIZE> buf);
 
#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
  void update_mdns_service_();
#endif
 
  // --- SendspinClientListener overrides ---
  void on_group_update(const sendspin::GroupUpdateObject &group) override;
 
  void on_request_high_performance() override;
 
  void on_release_high_performance() override;
 
  void on_open_pairing_window() override;
 
  void on_close_pairing_window() override;
 
  void on_display_pairing_code(const std::string &code, sendspin::SendspinPairingCodeFormat format) override;
 
  void on_clear_pairing_code() override;
 
  void on_pairing_succeeded(const std::string &server_id) override;
 
  void on_pairing_failed(const std::string &server_id, sendspin::SendspinPairAbortReason reason) override;
 
  // --- SendspinNetworkProvider override ---
  bool is_network_ready() override;
 
  // --- SendspinPersistenceProvider overrides ---
  // The library calls commit() after writing pairing secrets, so they reach flash right away.
  std::optional<std::vector<uint8_t>> load_blob(const std::string &key) override;
  bool save_blob(const std::string &key, const uint8_t *data, size_t len) override;
  bool commit() override;
 
  // --- Sendspin role specific methods/overrides/member variables ---
 
#ifdef USE_SENDSPIN_ARTWORK
  void on_image_decode(uint8_t slot, const uint8_t *data, size_t length, sendspin::SendspinImageFormat format) override;
 
  void on_image_display(uint8_t slot, uint32_t lateness_ms) override;
 
  void on_image_clear(uint8_t slot) override;
 
  sendspin::ArtworkRoleConfig artwork_config_{};
  sendspin::ArtworkRole *artwork_role_{nullptr};
 
  // Callback fan-out to child components; they filter by slot as needed.
  CallbackManager<void(uint8_t, const uint8_t *, size_t, sendspin::SendspinImageFormat)>
      artwork_image_decode_callbacks_{};
  CallbackManager<void(uint8_t, uint32_t)> artwork_image_display_callbacks_{};
  CallbackManager<void(uint8_t)> artwork_image_clear_callbacks_{};
#endif
 
#ifdef USE_SENDSPIN_CONTROLLER
  sendspin::ControllerRole *controller_role_{nullptr};
 
  void on_controller_state(const sendspin::ServerStateControllerObject &state) override;
 
  void on_controller_state_clear() override;
 
  // Callback fan-out to child components; they filter as needed. Only a media_player subscribes, while the switch
  // action and the media source enable the controller role without one, so keep the idle cost to a single pointer.
  LazyCallbackManager<void(const sendspin::ServerStateControllerObject &)> controller_state_callbacks_{};
  LazyCallbackManager<void()> controller_state_clear_callbacks_{};
#endif
 
#ifdef USE_SENDSPIN_METADATA
  sendspin::MetadataRole *metadata_role_{nullptr};
 
  void on_metadata(const sendspin::ServerMetadataStateObject &metadata) override;
 
  void on_metadata_clear() override;
 
  // Callback fan-out to child components; they filter as needed
  CallbackManager<void(const sendspin::ServerMetadataStateObject &)> metadata_update_callbacks_{};
#endif
 
#ifdef USE_SENDSPIN_PLAYER
  sendspin::PlayerRoleListener *player_listener_{nullptr};
  sendspin::PlayerRoleConfig player_config_{};
#endif
 
  // --- Core member variables ---
 
  // Built once in setup(): make_preference() allocates a backend that is never freed.
  ESPPreferenceObject keypair_pref_;
  ESPPreferenceObject pairing_psk_pref_;
  ESPPreferenceObject last_played_pref_;
  ESPPreferenceObject output_delay_pref_;
  std::array<ESPPreferenceObject, SENDSPIN_RECORD_SLOTS> record_slot_prefs_;
  ESPPreferenceObject record_order_pref_;
 
  std::unique_ptr<sendspin::SendspinClient> client_;
 
  // Callback fan-out to child components
  CallbackManager<void(const sendspin::GroupUpdateObject &)> group_update_callbacks_{};
 
  // Lazy: each pairing callback is fed by an optional YAML surface.
  LazyCallbackManager<void()> open_pairing_window_callbacks_{};
  LazyCallbackManager<void()> close_pairing_window_callbacks_{};
  LazyCallbackManager<void(const std::string &)> display_pairing_code_callbacks_{};
  LazyCallbackManager<void()> clear_pairing_code_callbacks_{};
  LazyCallbackManager<void(const std::string &)> pairing_succeeded_callbacks_{};
  LazyCallbackManager<void(const std::string &, StringRef)> pairing_failed_callbacks_{};
 
  const char *static_pairing_code_{nullptr};  // Codegen string literal, or nullptr when not configured
  bool pairing_code_display_supported_{false};
  bool task_stack_in_psram_{false};
#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
  bool mdns_advertised_{false};  // Last state requested from mdns
#endif
 
  // Requested client state, applied from loop(). The client does not start until both are set.
  std::optional<bool> enabled_;
  std::optional<bool> unpaired_access_;
 
  // Device information sent in the `client/hello` message. Defaults apply when neither the
  // sendspin configuration nor the project information supplies a value.
  const char *manufacturer_{"ESPHome"};
  const char *model_{nullptr};  // nullptr reports the device name instead
  const char *firmware_version_{ESPHOME_VERSION};
 
#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
  mdns::MDNSComponent *mdns_{nullptr};
#endif
};
 
class SendspinChild : public Component, public Parented<SendspinHub> {
 public:
  float get_setup_priority() const override { return sendspin_priority::CHILD; }
};
 
class SendspinPollingChild : public PollingComponent, public Parented<SendspinHub> {
 public:
  float get_setup_priority() const override { return sendspin_priority::CHILD; }
};
 
extern SendspinHub *global_sendspin_hub;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
}  // namespace esphome::sendspin_
 
#endif  // USE_ESP_IDF