ESPHome 2026.8.0b4
Loading...
Searching...
No Matches
esphome::sendspin_::SendspinHub Class Referencefinal

Thin adapter over sendspin::SendspinClient. More...

#include <sendspin_hub.h>

Inheritance diagram for esphome::sendspin_::SendspinHub:
esphome::Component

Public Member Functions

float get_setup_priority () const override
 
void setup () override
 
void loop () override
 
void dump_config () override
 
void connect_to_server (const std::string &url)
 Connects the underlying client to the given Sendspin server.
 
void disconnect_from_server (sendspin::SendspinGoodbyeReason reason)
 Disconnects the underlying client from the current server.
 
void update_state (sendspin::SendspinClientState state)
 Updates the client's reported playback state on the server.
 
template<typename F >
void add_group_update_callback (F &&callback)
 
void set_task_stack_in_psram (bool task_stack_in_psram)
 
void set_artwork_config (const sendspin::ArtworkRoleConfig &config)
 
void artwork_frame_done (uint8_t slot)
 Acknowledges the most recent artwork delivery (display or clear) for a slot.
 
template<typename F >
void add_image_decode_callback (F &&callback)
 
template<typename F >
void add_image_display_callback (F &&callback)
 
template<typename F >
void add_image_clear_callback (F &&callback)
 
void send_client_command (sendspin::SendspinControllerCommand command, std::optional< uint8_t > volume=std::nullopt, std::optional< bool > mute=std::nullopt)
 
template<typename F >
void add_controller_state_callback (F &&callback)
 
template<typename F >
void add_controller_state_clear_callback (F &&callback)
 Registers a callback that fires when the connection is lost and the cached controller state is dropped.
 
template<typename F >
void add_metadata_update_callback (F &&callback)
 Registers a callback that fires when the server sends metadata.
 
uint32_t get_track_progress_ms () const
 Returns the interpolated track progress in milliseconds, or 0 if the hub is not yet ready.
 
void set_listener (sendspin::PlayerRoleListener *listener)
 
void set_player_config (const sendspin::PlayerRoleConfig &config)
 
sendspin::PlayerRole * get_player_role ()
 Child components call this to get the PlayerRole instance after setup, so they can push updates to it.
 
- Public Member Functions inherited from esphome::Component
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
virtual bool teardown ()
 Called during teardown to allow component to gracefully finish operations.
 
virtual void on_powerdown ()
 Called after teardown is complete to power down hardware.
 
uint8_t get_component_state () const
 
void reset_to_construction_state ()
 Reset this component back to the construction state to allow setup to run again.
 
bool is_in_loop_state () const
 Check if this component has completed setup and is in the loop state.
 
bool is_idle () const
 Check if this component is idle.
 
void mark_failed ()
 Mark this component as failed.
 
void mark_failed (const LogString *message)
 
void disable_loop ()
 Disable this component's loop.
 
void enable_loop ()
 Enable this component's loop.
 
void enable_loop_soon_any_context ()
 Thread and ISR-safe version of enable_loop() that can be called from any context.
 
bool is_failed () const
 
bool is_ready () const
 
virtual bool can_proceed ()
 
bool status_has_warning () const
 
bool status_has_error () const
 
void status_set_warning ()
 
void status_set_warning (const char *message)
 
void status_set_warning (const LogString *message)
 
void status_set_error ()
 
void status_set_error (const LogString *message)
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const char *name, uint32_t length=5000)
 Set warning status flag and automatically clear it after a timeout.
 
void status_momentary_error (const char *name, uint32_t length=5000)
 Set error status flag and automatically clear it after a timeout.
 
bool has_overridden_loop () const
 
const LogString * get_component_log_str () const ESPHOME_ALWAYS_INLINE
 Get the integration where this component was declared as a LogString for logging.
 
bool should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)
 

Protected Member Functions

sendspin::SendspinClientConfig build_client_config_ ()
 Builds the SendspinClientConfig from ESPHome configuration and platform info.
 
void on_group_update (const sendspin::GroupUpdateObject &group) override
 
void on_request_high_performance () override
 
void on_release_high_performance () override
 
bool is_network_ready () override
 
bool save_last_server_hash (uint32_t hash) override
 
std::optional< uint32_tload_last_server_hash () override
 
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
 
void on_controller_state (const sendspin::ServerStateControllerObject &state) override
 
void on_controller_state_clear () override
 
void on_metadata (const sendspin::ServerMetadataStateObject &metadata) override
 
void on_metadata_clear () override
 
std::optional< uint16_t > load_static_delay () override
 
bool save_static_delay (uint16_t delay_ms) override
 
- Protected Member Functions inherited from esphome::Component
friend void::setup ()
 
friend void::original_setup ()
 
void set_component_source_ (uint8_t index)
 Set where this component was loaded from for some debug messages.
 
virtual void call_setup ()
 
void call_dump_config_ ()
 
void enable_loop_slow_path_ ()
 
void set_component_state_ (uint8_t state)
 Helper to set component state (clears state bits and sets new state)
 
bool set_status_flag_ (uint8_t flag)
 Helper to set a status LED flag on both this component and the app.
 
void set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a const char* name.
 
void set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a numeric ID (zero heap allocation).
 
void set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const char *name)
 Cancel an interval function.
 
bool cancel_interval (uint32_t id)
 
bool cancel_interval (InternalSchedulerID id)
 
void set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a const char* name.
 
void set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a numeric ID (zero heap allocation).
 
void set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (const char *name)
 Cancel a timeout function.
 
bool cancel_timeout (uint32_t id)
 
bool cancel_timeout (InternalSchedulerID id)
 
void defer (const char *name, std::function< void()> &&f)
 Defer a callback to the next loop() call with a const char* name.
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call.
 
void defer (uint32_t id, std::function< void()> &&f)
 Defer a callback with a numeric ID (zero heap allocation)
 
bool cancel_defer (const char *name)
 Cancel a defer callback using the specified name, name must not be empty.
 
bool cancel_defer (uint32_t id)
 
void status_clear_warning_slow_path_ ()
 
void status_clear_error_slow_path_ ()
 

Static Protected Member Functions

static const char * get_client_id_into_buffer (std::span< char, MAC_ADDRESS_PRETTY_BUFFER_SIZE > buf)
 Writes the active network interface's MAC into buf and returns its data pointer.
 

Protected Attributes

sendspin::ArtworkRoleConfig artwork_config_ {}
 
sendspin::ArtworkRole * artwork_role_ {nullptr}
 
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_ {}
 
sendspin::ControllerRole * controller_role_ {nullptr}
 
LazyCallbackManager< void(const sendspin::ServerStateControllerObject &)> controller_state_callbacks_ {}
 
LazyCallbackManager< void()> controller_state_clear_callbacks_ {}
 
sendspin::MetadataRole * metadata_role_ {nullptr}
 
CallbackManager< void(const sendspin::ServerMetadataStateObject &)> metadata_update_callbacks_ {}
 
sendspin::PlayerRoleListener * player_listener_ {nullptr}
 
sendspin::PlayerRoleConfig player_config_ {}
 
ESPPreferenceObject static_delay_pref_
 
ESPPreferenceObject last_played_server_pref_
 
std::unique_ptr< sendspin::SendspinClient > client_
 
CallbackManager< void(const sendspin::GroupUpdateObject &)> group_update_callbacks_ {}
 
bool task_stack_in_psram_ {false}
 
- Protected Attributes inherited from esphome::Component
uint8_t component_source_index_ {0}
 Index into component source PROGMEM lookup table (0 = not set)
 
uint8_t warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
 Warn threshold in centiseconds (max 2550ms)
 
uint8_t component_state_ {0x00}
 State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.
 
volatile bool pending_enable_loop_ {false}
 ISR-safe flag for enable_loop_soon_any_context.
 
ComponentRuntimeStats runtime_stats_
 

Detailed Description

Thin adapter over sendspin::SendspinClient.

The hub owns a SendspinClient instance and bridges its listener/provider interfaces to ESPHome's CallbackManager for fan-out to child components.

  • Provides persistence via ESPPreferenceObject and WiFi power management integration.
  • Handles Sendspin roles that apply to multiple child components (artwork, controller, metadata) so their events can be fanned out. Roles specific to a single component (player) are configured by the hub but owned by the child thereafter, since no fan-out is needed.

The sendspin-cpp library follows this design:

  • Core and role configuration are passed at client/role construction time as structs. Built in our setup().
  • Library -> user code communication happens via two interface types the user implements and registers in our setup(): listener interfaces (for events the library pushes; e.g., group updates) and provider interfaces (for services the library pulls; e.g., persistence, network readiness).
  • User -> library communication uses exposed functions on the client and role objects that the user calls.

Definition at line 74 of file sendspin_hub.h.

Member Function Documentation

◆ add_controller_state_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_controller_state_callback ( F && callback)
inline

Definition at line 155 of file sendspin_hub.h.

◆ add_controller_state_clear_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_controller_state_clear_callback ( F && callback)
inline

Registers a callback that fires when the connection is lost and the cached controller state is dropped.

Definition at line 160 of file sendspin_hub.h.

◆ add_group_update_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_group_update_callback ( F && callback)
inline

Definition at line 122 of file sendspin_hub.h.

◆ add_image_clear_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_image_clear_callback ( F && callback)
inline

Definition at line 146 of file sendspin_hub.h.

◆ add_image_decode_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_image_decode_callback ( F && callback)
inline

Definition at line 140 of file sendspin_hub.h.

◆ add_image_display_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_image_display_callback ( F && callback)
inline

Definition at line 143 of file sendspin_hub.h.

◆ add_metadata_update_callback()

template<typename F >
void esphome::sendspin_::SendspinHub::add_metadata_update_callback ( F && callback)
inline

Registers a callback that fires when the server sends metadata.

Also fires when the connection is lost, with an all-empty state object (every field nullopt, timestamp 0) meaning the cached metadata was dropped. Subscribers must treat an absent field as cleared, not as no update.

Definition at line 170 of file sendspin_hub.h.

◆ artwork_frame_done()

void esphome::sendspin_::SendspinHub::artwork_frame_done ( uint8_t slot)

Acknowledges the most recent artwork delivery (display or clear) for a slot.

Every slot is configured with the library's require_frame_done gate, which withholds the next delivery for the slot until this is called. Exactly one ack is owed per delivery; a redundant call is a safe no-op in the library. Must be called from the main loop thread.

Definition at line 217 of file sendspin_hub.cpp.

◆ build_client_config_()

sendspin::SendspinClientConfig esphome::sendspin_::SendspinHub::build_client_config_ ( )
protected

Builds the SendspinClientConfig from ESPHome configuration and platform info.

Definition at line 130 of file sendspin_hub.cpp.

◆ connect_to_server()

void esphome::sendspin_::SendspinHub::connect_to_server ( const std::string & url)

Connects the underlying client to the given Sendspin server.

No-op if the hub's client is not ready (e.g. setup() has not completed). Must be called from the main loop thread.

Parameters
urlWebSocket URL of the Sendspin server, starting with ws:// (e.g. ws://host:port/path).

Definition at line 98 of file sendspin_hub.cpp.

◆ disconnect_from_server()

void esphome::sendspin_::SendspinHub::disconnect_from_server ( sendspin::SendspinGoodbyeReason reason)

Disconnects the underlying client from the current server.

Sends a client/goodbye message with the given reason before closing the connection. No-op if the hub's client is not ready. Must be called from the main loop thread.

Parameters
reasonReason reported to the server:
  • ANOTHER_SERVER: client is switching to another server.
  • SHUTDOWN: client is shutting down.
  • RESTART: client is restarting.
  • USER_REQUEST: user explicitly requested disconnect.

Definition at line 105 of file sendspin_hub.cpp.

◆ dump_config()

void esphome::sendspin_::SendspinHub::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 74 of file sendspin_hub.cpp.

◆ get_client_id_into_buffer()

const char * esphome::sendspin_::SendspinHub::get_client_id_into_buffer ( std::span< char, MAC_ADDRESS_PRETTY_BUFFER_SIZE > buf)
staticprotected

Writes the active network interface's MAC into buf and returns its data pointer.

Uses the ethernet MAC if ethernet is configured, otherwise the base MAC (used by wifi).

Definition at line 118 of file sendspin_hub.cpp.

◆ get_player_role()

sendspin::PlayerRole * esphome::sendspin_::SendspinHub::get_player_role ( )

Child components call this to get the PlayerRole instance after setup, so they can push updates to it.

Definition at line 273 of file sendspin_hub.cpp.

◆ get_setup_priority()

float esphome::sendspin_::SendspinHub::get_setup_priority ( ) const
inlineoverridevirtual

Reimplemented from esphome::Component.

Definition at line 88 of file sendspin_hub.h.

◆ get_track_progress_ms()

uint32_t esphome::sendspin_::SendspinHub::get_track_progress_ms ( ) const

Returns the interpolated track progress in milliseconds, or 0 if the hub is not yet ready.

Definition at line 263 of file sendspin_hub.cpp.

◆ is_network_ready()

bool esphome::sendspin_::SendspinHub::is_network_ready ( )
overrideprotected

Definition at line 172 of file sendspin_hub.cpp.

◆ load_last_server_hash()

std::optional< uint32_t > esphome::sendspin_::SendspinHub::load_last_server_hash ( )
overrideprotected

Definition at line 189 of file sendspin_hub.cpp.

◆ load_static_delay()

std::optional< uint16_t > esphome::sendspin_::SendspinHub::load_static_delay ( )
overrideprotected

Definition at line 293 of file sendspin_hub.cpp.

◆ loop()

void esphome::sendspin_::SendspinHub::loop ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 72 of file sendspin_hub.cpp.

◆ on_controller_state()

void esphome::sendspin_::SendspinHub::on_controller_state ( const sendspin::ServerStateControllerObject & state)
overrideprotected

Definition at line 239 of file sendspin_hub.cpp.

◆ on_controller_state_clear()

void esphome::sendspin_::SendspinHub::on_controller_state_clear ( )
overrideprotected

Definition at line 247 of file sendspin_hub.cpp.

◆ on_group_update()

void esphome::sendspin_::SendspinHub::on_group_update ( const sendspin::GroupUpdateObject & group)
overrideprotected

Definition at line 147 of file sendspin_hub.cpp.

◆ on_image_clear()

void esphome::sendspin_::SendspinHub::on_image_clear ( uint8_t slot)
overrideprotected

Definition at line 214 of file sendspin_hub.cpp.

◆ on_image_decode()

void esphome::sendspin_::SendspinHub::on_image_decode ( uint8_t slot,
const uint8_t * data,
size_t length,
sendspin::SendspinImageFormat format )
overrideprotected

Definition at line 202 of file sendspin_hub.cpp.

◆ on_image_display()

void esphome::sendspin_::SendspinHub::on_image_display ( uint8_t slot,
uint32_t lateness_ms )
overrideprotected

Definition at line 209 of file sendspin_hub.cpp.

◆ on_metadata()

void esphome::sendspin_::SendspinHub::on_metadata ( const sendspin::ServerMetadataStateObject & metadata)
overrideprotected

Definition at line 252 of file sendspin_hub.cpp.

◆ on_metadata_clear()

void esphome::sendspin_::SendspinHub::on_metadata_clear ( )
overrideprotected

Definition at line 260 of file sendspin_hub.cpp.

◆ on_release_high_performance()

void esphome::sendspin_::SendspinHub::on_release_high_performance ( )
overrideprotected

Definition at line 160 of file sendspin_hub.cpp.

◆ on_request_high_performance()

void esphome::sendspin_::SendspinHub::on_request_high_performance ( )
overrideprotected

Definition at line 151 of file sendspin_hub.cpp.

◆ save_last_server_hash()

bool esphome::sendspin_::SendspinHub::save_last_server_hash ( uint32_t hash)
overrideprotected

Definition at line 177 of file sendspin_hub.cpp.

◆ save_static_delay()

bool esphome::sendspin_::SendspinHub::save_static_delay ( uint16_t delay_ms)
overrideprotected

Definition at line 281 of file sendspin_hub.cpp.

◆ send_client_command()

void esphome::sendspin_::SendspinHub::send_client_command ( sendspin::SendspinControllerCommand command,
std::optional< uint8_t > volume = std::nullopt,
std::optional< bool > mute = std::nullopt )

Definition at line 226 of file sendspin_hub.cpp.

◆ set_artwork_config()

void esphome::sendspin_::SendspinHub::set_artwork_config ( const sendspin::ArtworkRoleConfig & config)
inline

Definition at line 131 of file sendspin_hub.h.

◆ set_listener()

void esphome::sendspin_::SendspinHub::set_listener ( sendspin::PlayerRoleListener * listener)
inline

Definition at line 179 of file sendspin_hub.h.

◆ set_player_config()

void esphome::sendspin_::SendspinHub::set_player_config ( const sendspin::PlayerRoleConfig & config)
inline

Definition at line 180 of file sendspin_hub.h.

◆ set_task_stack_in_psram()

void esphome::sendspin_::SendspinHub::set_task_stack_in_psram ( bool task_stack_in_psram)
inline

Definition at line 126 of file sendspin_hub.h.

◆ setup()

void esphome::sendspin_::SendspinHub::setup ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 30 of file sendspin_hub.cpp.

◆ update_state()

void esphome::sendspin_::SendspinHub::update_state ( sendspin::SendspinClientState state)

Updates the client's reported playback state on the server.

No-op if the hub's client is not ready. Must be called from the main loop thread.

Parameters
stateNew client state:
  • SYNCHRONIZED: client is synchronized and playing from the server.
  • ERROR: client encountered a playback error.
  • EXTERNAL_SOURCE: client is playing from a non-Sendspin source.

Definition at line 112 of file sendspin_hub.cpp.

Field Documentation

◆ artwork_config_

sendspin::ArtworkRoleConfig esphome::sendspin_::SendspinHub::artwork_config_ {}
protected

Definition at line 217 of file sendspin_hub.h.

◆ artwork_image_clear_callbacks_

CallbackManager<void(uint8_t)> esphome::sendspin_::SendspinHub::artwork_image_clear_callbacks_ {}
protected

Definition at line 224 of file sendspin_hub.h.

◆ artwork_image_decode_callbacks_

CallbackManager<void(uint8_t, const uint8_t *, size_t, sendspin::SendspinImageFormat)> esphome::sendspin_::SendspinHub::artwork_image_decode_callbacks_ {}
protected

Definition at line 222 of file sendspin_hub.h.

◆ artwork_image_display_callbacks_

CallbackManager<void(uint8_t, uint32_t)> esphome::sendspin_::SendspinHub::artwork_image_display_callbacks_ {}
protected

Definition at line 223 of file sendspin_hub.h.

◆ artwork_role_

sendspin::ArtworkRole* esphome::sendspin_::SendspinHub::artwork_role_ {nullptr}
protected

Definition at line 218 of file sendspin_hub.h.

◆ client_

std::unique_ptr<sendspin::SendspinClient> esphome::sendspin_::SendspinHub::client_
protected

Definition at line 265 of file sendspin_hub.h.

◆ controller_role_

sendspin::ControllerRole* esphome::sendspin_::SendspinHub::controller_role_ {nullptr}
protected

Definition at line 228 of file sendspin_hub.h.

◆ controller_state_callbacks_

LazyCallbackManager<void(const sendspin::ServerStateControllerObject &)> esphome::sendspin_::SendspinHub::controller_state_callbacks_ {}
protected

Definition at line 236 of file sendspin_hub.h.

◆ controller_state_clear_callbacks_

LazyCallbackManager<void()> esphome::sendspin_::SendspinHub::controller_state_clear_callbacks_ {}
protected

Definition at line 237 of file sendspin_hub.h.

◆ group_update_callbacks_

CallbackManager<void(const sendspin::GroupUpdateObject &)> esphome::sendspin_::SendspinHub::group_update_callbacks_ {}
protected

Definition at line 268 of file sendspin_hub.h.

◆ last_played_server_pref_

ESPPreferenceObject esphome::sendspin_::SendspinHub::last_played_server_pref_
protected

Definition at line 263 of file sendspin_hub.h.

◆ metadata_role_

sendspin::MetadataRole* esphome::sendspin_::SendspinHub::metadata_role_ {nullptr}
protected

Definition at line 241 of file sendspin_hub.h.

◆ metadata_update_callbacks_

CallbackManager<void(const sendspin::ServerMetadataStateObject &)> esphome::sendspin_::SendspinHub::metadata_update_callbacks_ {}
protected

Definition at line 248 of file sendspin_hub.h.

◆ player_config_

sendspin::PlayerRoleConfig esphome::sendspin_::SendspinHub::player_config_ {}
protected

Definition at line 253 of file sendspin_hub.h.

◆ player_listener_

sendspin::PlayerRoleListener* esphome::sendspin_::SendspinHub::player_listener_ {nullptr}
protected

Definition at line 252 of file sendspin_hub.h.

◆ static_delay_pref_

ESPPreferenceObject esphome::sendspin_::SendspinHub::static_delay_pref_
protected

Definition at line 256 of file sendspin_hub.h.

◆ task_stack_in_psram_

bool esphome::sendspin_::SendspinHub::task_stack_in_psram_ {false}
protected

Definition at line 270 of file sendspin_hub.h.


The documentation for this class was generated from the following files: