ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
sendspin_hub.h
Go to the documentation of this file.
1#pragma once
2
4
5#ifdef USE_ESP_IDF
6
13
14#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
16#endif
17#ifdef USE_SENDSPIN_ENABLED_SWITCH
19#endif
20
21#include <sendspin/client.h>
22#include <sendspin/config.h>
23#include <sendspin/types.h>
24
25#ifdef USE_SENDSPIN_ARTWORK
26#include <sendspin/artwork_role.h>
27#endif
28#ifdef USE_SENDSPIN_CONTROLLER
29#include <sendspin/controller_role.h>
30#endif
31#ifdef USE_SENDSPIN_METADATA
32#include <sendspin/metadata_role.h>
33#endif
34#ifdef USE_SENDSPIN_PLAYER
35#include <sendspin/player_role.h>
36#endif
37#ifdef USE_SENDSPIN_SOURCE
39
40#include <sendspin/source_role.h>
41#endif
42
43#include <array>
44#include <cstddef>
45#include <cstdint>
46#include <functional>
47#include <memory>
48#include <optional>
49#include <string>
50#include <utility>
51#include <vector>
52
53namespace esphome::sendspin_ {
54
60namespace sendspin_priority {
61// AFTER_WIFI so the hub runs after the wifi/ethernet drivers are up and we can read the active
62// interface's MAC address for the device info.
64inline constexpr float CHILD = HUB - 1.0f;
65} // namespace sendspin_priority
66
67// PREFERENCE KEYS: each library persistence key has its own preference, hashed from "sendspin_" + name. Renaming
68// one erases it.
69
71inline constexpr size_t SENDSPIN_RECORD_SLOTS = sendspin::SendspinClientConfig::DEFAULT_MAX_PAIRING_RECORDS;
72
77
94class SendspinHub final : public Component,
95#ifdef USE_SENDSPIN_ARTWORK
96 public sendspin::ArtworkRoleListener,
97#endif
98#ifdef USE_SENDSPIN_CONTROLLER
99 public sendspin::ControllerRoleListener,
100#endif
101#ifdef USE_SENDSPIN_METADATA
102 public sendspin::MetadataRoleListener,
103#endif
104#ifdef USE_SENDSPIN_SOURCE
105 public sendspin::SourceRoleListener,
106#endif
107 public sendspin::SendspinClientListener,
108 public sendspin::SendspinNetworkProvider,
109 public sendspin::SendspinPersistenceProvider {
110 public:
111 SendspinHub();
112
113 float get_setup_priority() const override { return sendspin_priority::HUB; }
114 void setup() override;
115 void loop() override;
116 void on_shutdown() override;
117 void dump_config() override;
118
124 void connect_to_server(const std::string &url);
125
135 void disconnect_from_server(sendspin::SendspinGoodbyeReason reason);
136
141 void leave_group();
142
148
153
154 // --- Configuration setters (called from codegen) ---
155
156 template<typename F> void add_group_update_callback(F &&callback) {
157 this->group_update_callbacks_.add(std::forward<F>(callback));
158 }
159
160 template<typename F> void add_on_open_pairing_window_callback(F &&callback) {
161 this->open_pairing_window_callbacks_.add(std::forward<F>(callback));
162 }
163
164 template<typename F> void add_on_close_pairing_window_callback(F &&callback) {
165 this->close_pairing_window_callbacks_.add(std::forward<F>(callback));
166 }
167
168 template<typename F> void add_on_display_pairing_code_callback(F &&callback) {
169 this->display_pairing_code_callbacks_.add(std::forward<F>(callback));
170 }
171
172 template<typename F> void add_on_clear_pairing_code_callback(F &&callback) {
173 this->clear_pairing_code_callbacks_.add(std::forward<F>(callback));
174 }
175
176 template<typename F> void add_on_pairing_succeeded_callback(F &&callback) {
177 this->pairing_succeeded_callbacks_.add(std::forward<F>(callback));
178 }
179
180 template<typename F> void add_on_pairing_failed_callback(F &&callback) {
181 this->pairing_failed_callbacks_.add(std::forward<F>(callback));
182 }
183
184 void set_task_stack_in_psram(bool task_stack_in_psram) { this->task_stack_in_psram_ = task_stack_in_psram; }
185
192 void set_enabled(bool enabled);
193#ifdef USE_SENDSPIN_ENABLED_SWITCH
194 SUB_SWITCH(enabled)
195#endif
196
199 void set_unpaired_access_enabled(bool enabled);
200
202 bool is_client_running() const { return this->client_ != nullptr && this->client_->is_started(); }
203
205 bool is_disabled() const { return this->enabled_.has_value() && !this->enabled_.value(); }
206
209
214 std::optional<std::string> get_pairing_token() const;
215
220 StringRef get_client_id() const;
221
227 void set_manufacturer(const char *manufacturer) { this->manufacturer_ = manufacturer; }
228 void set_model(const char *model) { this->model_ = model; }
229 void set_firmware_version(const char *firmware_version) { this->firmware_version_ = firmware_version; }
230
231#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
232 void set_mdns(mdns::MDNSComponent *mdns) { this->mdns_ = mdns; }
233#endif
234
236 void set_static_pairing_code(const char *code) { this->static_pairing_code_ = code; }
237
240 void set_pairing_code_display_supported(bool supported) { this->pairing_code_display_supported_ = supported; }
241
242 // --- Sendspin role specific methods ---
243
244#ifdef USE_SENDSPIN_ARTWORK
245 void set_artwork_config(const sendspin::ArtworkRoleConfig &config) { this->artwork_config_ = config; }
246
252 void artwork_frame_done(uint8_t slot);
253
254 template<typename F> void add_image_decode_callback(F &&callback) {
255 this->artwork_image_decode_callbacks_.add(std::forward<F>(callback));
256 }
257 template<typename F> void add_image_display_callback(F &&callback) {
258 this->artwork_image_display_callbacks_.add(std::forward<F>(callback));
259 }
260 template<typename F> void add_image_clear_callback(F &&callback) {
261 this->artwork_image_clear_callbacks_.add(std::forward<F>(callback));
262 }
263#endif
264
265#ifdef USE_SENDSPIN_CONTROLLER
266 void send_client_command(sendspin::SendspinControllerCommand command, std::optional<uint8_t> volume = std::nullopt,
267 std::optional<bool> mute = std::nullopt);
268
270 void switch_client();
271
272 template<typename F> void add_controller_state_callback(F &&callback) {
273 this->controller_state_callbacks_.add(std::forward<F>(callback));
274 }
275
277 template<typename F> void add_controller_state_clear_callback(F &&callback) {
278 this->controller_state_clear_callbacks_.add(std::forward<F>(callback));
279 }
280#endif
281
282#ifdef USE_SENDSPIN_METADATA
287 template<typename F> void add_metadata_update_callback(F &&callback) {
288 this->metadata_update_callbacks_.add(std::forward<F>(callback));
289 }
290
293#endif
294
295#ifdef USE_SENDSPIN_PLAYER
296 void set_listener(sendspin::PlayerRoleListener *listener) { this->player_listener_ = listener; }
297 void set_player_config(const sendspin::PlayerRoleConfig &config) { this->player_config_ = config; }
298
300 sendspin::PlayerRole *get_player_role();
301#endif
302
303#ifdef USE_SENDSPIN_SOURCE
304 void set_source_config(const sendspin::SourceRoleConfig &config) { this->source_config_ = config; }
306 this->microphone_source_ = microphone_source;
307 }
308
312 void set_source_signal(bool present);
313
315 bool is_source_streaming() const { return this->source_role_ != nullptr && this->source_role_->is_streaming(); }
316
318 template<typename F> void add_on_source_streaming_started_callback(F &&callback) {
319 this->source_streaming_started_callbacks_.add(std::forward<F>(callback));
320 }
322 template<typename F> void add_on_source_streaming_stopped_callback(F &&callback) {
323 this->source_streaming_stopped_callbacks_.add(std::forward<F>(callback));
324 }
325#endif
326
327 protected:
329 sendspin::SendspinClientConfig build_client_config_();
330
333 std::pair<ESPPreferenceObject *, size_t> pref_for_key_(const std::string &key);
334
336 const char *get_product_name_() const;
337
338 const char *pairing_code_method_() const;
339
342 static const char *get_mac_address_into_buffer(std::span<char, MAC_ADDRESS_PRETTY_BUFFER_SIZE> buf);
343
344#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
347#endif
348
349 // --- SendspinClientListener overrides ---
350 void on_group_update(const sendspin::GroupUpdateObject &group) override;
351
352 void on_request_high_performance() override;
353
354 void on_release_high_performance() override;
355
356 void on_open_pairing_window() override;
357
358 void on_close_pairing_window() override;
359
360 void on_display_pairing_code(const std::string &code, sendspin::SendspinPairingCodeFormat format) override;
361
362 void on_clear_pairing_code() override;
363
364 void on_pairing_succeeded(const std::string &server_id) override;
365
366 void on_pairing_failed(const std::string &server_id, sendspin::SendspinPairAbortReason reason) override;
367
368 // --- SendspinNetworkProvider override ---
369 bool is_network_ready() override;
370
371 // --- SendspinPersistenceProvider overrides ---
372 // The library calls commit() after writing pairing secrets, so they reach flash right away.
373 std::optional<std::vector<uint8_t>> load_blob(const std::string &key) override;
374 bool save_blob(const std::string &key, const uint8_t *data, size_t len) override;
375 bool commit() override;
376
377 // --- Sendspin role specific methods/overrides/member variables ---
378
379#ifdef USE_SENDSPIN_ARTWORK
380 void on_image_decode(uint8_t slot, const uint8_t *data, size_t length, sendspin::SendspinImageFormat format) override;
381
382 void on_image_display(uint8_t slot, uint32_t lateness_ms) override;
383
384 void on_image_clear(uint8_t slot) override;
385
386 sendspin::ArtworkRoleConfig artwork_config_{};
387 sendspin::ArtworkRole *artwork_role_{nullptr};
388
389 // Callback fan-out to child components; they filter by slot as needed.
390 CallbackManager<void(uint8_t, const uint8_t *, size_t, sendspin::SendspinImageFormat)>
394#endif
395
396#ifdef USE_SENDSPIN_CONTROLLER
397 sendspin::ControllerRole *controller_role_{nullptr};
398
399 void on_controller_state(const sendspin::ServerStateControllerObject &state) override;
400
401 void on_controller_state_clear() override;
402
403 // Callback fan-out to child components; they filter as needed. Only a media_player subscribes, while the switch
404 // action and the media source enable the controller role without one, so keep the idle cost to a single pointer.
405 LazyCallbackManager<void(const sendspin::ServerStateControllerObject &)> controller_state_callbacks_{};
407#endif
408
409#ifdef USE_SENDSPIN_METADATA
410 sendspin::MetadataRole *metadata_role_{nullptr};
411
412 void on_metadata(const sendspin::ServerMetadataStateObject &metadata) override;
413
414 void on_metadata_clear() override;
415
416 // Callback fan-out to child components; they filter as needed
417 CallbackManager<void(const sendspin::ServerMetadataStateObject &)> metadata_update_callbacks_{};
418#endif
419
420#ifdef USE_SENDSPIN_PLAYER
421 sendspin::PlayerRoleListener *player_listener_{nullptr};
422 sendspin::PlayerRoleConfig player_config_{};
423#endif
424
425#ifdef USE_SENDSPIN_SOURCE
426 // The server opens and closes the stream; the microphone runs only while it is open.
427 void on_streaming_started() override;
428 void on_streaming_stopped() override;
429
430 sendspin::SourceRoleConfig source_config_{};
431 sendspin::SourceRole *source_role_{nullptr};
433 // Signal set before setup(), applied once the role exists
434 bool source_signal_{false};
435
436 // Lazy: each is fed by an optional YAML automation.
439#endif
440
441 // --- Core member variables ---
442
443 // Built once in setup(): make_preference() allocates a backend that is never freed.
448 std::array<ESPPreferenceObject, SENDSPIN_RECORD_SLOTS> record_slot_prefs_;
450
451 std::unique_ptr<sendspin::SendspinClient> client_;
452
453 // Callback fan-out to child components
454 CallbackManager<void(const sendspin::GroupUpdateObject &)> group_update_callbacks_{};
455
456 // Lazy: each pairing callback is fed by an optional YAML surface.
463
464 const char *static_pairing_code_{nullptr}; // Codegen string literal, or nullptr when not configured
467#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
468 bool mdns_advertised_{false}; // Last state requested from mdns
469#endif
470
471 // Requested client state, applied from loop(). The client does not start until both are set.
472 std::optional<bool> enabled_;
473 std::optional<bool> unpaired_access_;
474
475 // Device information sent in the `client/hello` message. Defaults apply when neither the
476 // sendspin configuration nor the project information supplies a value.
477 const char *manufacturer_{"ESPHome"};
478 const char *model_{nullptr}; // nullptr reports the device name instead
479 const char *firmware_version_{ESPHOME_VERSION};
480
481#ifdef USE_MDNS_SUPPORTS_ENABLE_DISABLE
483#endif
484};
485
492class SendspinChild : public Component, public Parented<SendspinHub> {
493 public:
494 float get_setup_priority() const override { return sendspin_priority::CHILD; }
495};
496
502class SendspinPollingChild : public PollingComponent, public Parented<SendspinHub> {
503 public:
504 float get_setup_priority() const override { return sendspin_priority::CHILD; }
505};
506
507extern SendspinHub *global_sendspin_hub; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
508
509} // namespace esphome::sendspin_
510
511#endif // USE_ESP_IDF
Helper class to easily give an object a parent of type T.
Definition helpers.h:2160
This class simplifies creating components that periodically check a state.
Definition component.h:532
StringRef is a reference to a string owned by something else.
Definition string_ref.h:31
Base class for all sendspin subcomponents.
float get_setup_priority() const override
Thin adapter over sendspin::SendspinClient.
ESPPreferenceObject output_delay_pref_
uint32_t get_feature_flags() const
Returns the SendspinFeature flags reported to API clients.
sendspin::SourceRole * source_role_
CallbackManager< void(uint8_t, const uint8_t *, size_t, sendspin::SendspinImageFormat)> artwork_image_decode_callbacks_
void add_image_clear_callback(F &&callback)
CallbackManager< void(uint8_t, uint32_t)> artwork_image_display_callbacks_
sendspin::PlayerRoleListener * player_listener_
void set_firmware_version(const char *firmware_version)
void add_on_clear_pairing_code_callback(F &&callback)
const char * get_product_name_() const
Returns the product name reported to the server: the configured model, or the device name.
void set_static_pairing_code(const char *code)
The static pairing code, used on every boot.
std::optional< bool > unpaired_access_
void on_controller_state_clear() override
std::optional< std::vector< uint8_t > > load_blob(const std::string &key) override
void set_artwork_config(const sendspin::ArtworkRoleConfig &config)
void confirm_pairing_window()
Confirms a pairing attempt on the device.
CallbackManager< void(const sendspin::ServerMetadataStateObject &)> metadata_update_callbacks_
ESPPreferenceObject record_order_pref_
microphone::MicrophoneSource * microphone_source_
std::optional< std::string > get_pairing_token() const
Returns the pairing token a Sendspin server uses to pair with this device.
LazyCallbackManager< void(const std::string &, StringRef)> pairing_failed_callbacks_
void add_image_decode_callback(F &&callback)
void add_on_source_streaming_started_callback(F &&callback)
Registers a callback that fires when the server opens the source stream.
LazyCallbackManager< void(const sendspin::ServerStateControllerObject &)> controller_state_callbacks_
void add_group_update_callback(F &&callback)
void on_release_high_performance() override
void set_manufacturer(const char *manufacturer)
Sets the device information reported to the server in the client/hello message.
bool save_blob(const std::string &key, const uint8_t *data, size_t len) override
LazyCallbackManager< void()> clear_pairing_code_callbacks_
sendspin::MetadataRole * metadata_role_
void on_display_pairing_code(const std::string &code, sendspin::SendspinPairingCodeFormat format) override
void set_source_config(const sendspin::SourceRoleConfig &config)
bool is_source_streaming() const
Returns whether the source is streaming microphone audio to the server.
bool is_client_running() const
Returns whether the Sendspin client is running.
void add_on_open_pairing_window_callback(F &&callback)
const char * pairing_code_method_() const
CallbackManager< void(const sendspin::GroupUpdateObject &)> group_update_callbacks_
LazyCallbackManager< void(const std::string &)> display_pairing_code_callbacks_
void switch_client()
Sends the SWITCH controller command; exposed as the sendspin.switch action.
void add_on_source_streaming_stopped_callback(F &&callback)
Registers a callback that fires when the source stream closes.
void leave_group()
Leaves the current group so another source can use the speaker.
sendspin::PlayerRoleConfig player_config_
void set_pairing_code_display_supported(bool supported)
Set when on_display_pairing_code or a pairing_code text sensor is configured, so the device offers th...
void on_metadata(const sendspin::ServerMetadataStateObject &metadata) override
void cancel_pairing_window()
Closes an open pairing window, so a waiting pairing attempt is not confirmed.
void add_on_pairing_succeeded_callback(F &&callback)
ESPPreferenceObject last_played_pref_
void add_on_close_pairing_window_callback(F &&callback)
void set_player_config(const sendspin::PlayerRoleConfig &config)
LazyCallbackManager< void(const std::string &)> pairing_succeeded_callbacks_
static const char * get_mac_address_into_buffer(std::span< char, MAC_ADDRESS_PRETTY_BUFFER_SIZE > buf)
Writes the active network interface's MAC, in lowercase, into buf and returns its data pointer.
sendspin::PlayerRole * get_player_role()
Child components call this to get the PlayerRole instance after setup, so they can push updates to it...
void set_listener(sendspin::PlayerRoleListener *listener)
void on_image_clear(uint8_t slot) override
void on_pairing_failed(const std::string &server_id, sendspin::SendspinPairAbortReason reason) override
void add_controller_state_clear_callback(F &&callback)
Registers a callback that fires when the connection is lost and the cached controller state is droppe...
bool is_disabled() const
Returns whether the client has been turned off with set_enabled().
void disconnect_from_server(sendspin::SendspinGoodbyeReason reason)
Disconnects the underlying client from the current server.
std::unique_ptr< sendspin::SendspinClient > client_
sendspin::ArtworkRoleConfig artwork_config_
void update_mdns_service_()
Keeps the _sendspin mDNS service advertised while the client is running.
LazyCallbackManager< void()> source_streaming_started_callbacks_
void add_on_pairing_failed_callback(F &&callback)
LazyCallbackManager< void()> source_streaming_stopped_callbacks_
sendspin::SendspinClientConfig build_client_config_()
Builds the SendspinClientConfig from ESPHome configuration and platform info.
mdns::MDNSComponent * mdns_
sendspin::ControllerRole * controller_role_
void on_pairing_succeeded(const std::string &server_id) override
void add_on_display_pairing_code_callback(F &&callback)
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_microphone_source(microphone::MicrophoneSource *microphone_source)
void add_controller_state_callback(F &&callback)
std::optional< bool > enabled_
StringRef get_client_id() const
Returns the Sendspin client_id: base64url of the client's static public key.
void set_mdns(mdns::MDNSComponent *mdns)
void send_client_command(sendspin::SendspinControllerCommand command, std::optional< uint8_t > volume=std::nullopt, std::optional< bool > mute=std::nullopt)
void set_model(const char *model)
LazyCallbackManager< void()> controller_state_clear_callbacks_
sendspin::SourceRoleConfig source_config_
CallbackManager< void(uint8_t)> artwork_image_clear_callbacks_
ESPPreferenceObject keypair_pref_
LazyCallbackManager< void()> open_pairing_window_callbacks_
SUB_SWITCH(enabled) void set_unpaired_access_enabled(bool enabled)
Turns unpaired (Sentinel) access on or off.
void set_task_stack_in_psram(bool task_stack_in_psram)
sendspin::ArtworkRole * artwork_role_
void on_request_high_performance() override
float get_setup_priority() const override
std::pair< ESPPreferenceObject *, size_t > pref_for_key_(const std::string &key)
The preference a library key is stored in and its blob size, or {nullptr, 0} for a key with no storag...
void set_enabled(bool enabled)
Requests the Sendspin client, including the server, the roles and the mDNS advertisement,...
std::array< ESPPreferenceObject, SENDSPIN_RECORD_SLOTS > record_slot_prefs_
void on_image_display(uint8_t slot, uint32_t lateness_ms) override
void on_image_decode(uint8_t slot, const uint8_t *data, size_t length, sendspin::SendspinImageFormat format) override
ESPPreferenceObject pairing_psk_pref_
void on_controller_state(const sendspin::ServerStateControllerObject &state) override
LazyCallbackManager< void()> close_pairing_window_callbacks_
void connect_to_server(const std::string &url)
Connects the underlying client to the given Sendspin server.
void add_image_display_callback(F &&callback)
void on_group_update(const sendspin::GroupUpdateObject &group) override
void set_source_signal(bool present)
Reports whether the source has audio to offer; exposed as the sendspin.source.set_signal action.
void add_metadata_update_callback(F &&callback)
Registers a callback that fires when the server sends metadata.
void artwork_frame_done(uint8_t slot)
Acknowledges the most recent artwork delivery (display or clear) for a slot.
Base class for sendspin subcomponents that need polling behavior.
float get_setup_priority() const override
const char * key
bool state
Definition fan.h:2
const char * format
constexpr size_t SENDSPIN_RECORD_SLOTS
Pairing-record slots, handed to the client as max_pairing_records.
SendspinFeature
Feature flags reported to API clients in DeviceCapabilitiesResponse.
SendspinHub * global_sendspin_hub
constexpr float AFTER_WIFI
For components that should be initialized after WiFi is connected.
Definition component.h:55
const void size_t len
Definition hal.h:68
static void uint32_t