new usermod hooks "onUdpPacket"

this new hooks will help you implement new and custom protocols in
usermods.
I've provided an example (see usermods/udp_name_sync).
The example will help you share the main segment name across different
WLED instances.
The segment name can be useful to sync with some effects like GIF
image or scrolling text.

If you define new packet format in your usermod, make sure it will
either not collide with already used version of wled udp packet :
- 0 is for udp sync
- 1 is for AudioReactive data
- 2 is for udp_name_sync :)

Also, the onUdpPacket will override "parseNotification" if it returns "true".
Have fun!
This commit is contained in:
Arthur Suzuki
2025-08-21 01:00:22 +02:00
parent 7285efebca
commit 4de6656bc4
5 changed files with 93 additions and 0 deletions

View File

@@ -442,6 +442,7 @@ class Usermod {
virtual void onMqttConnect(bool sessionPresent) {} // fired when MQTT connection is established (so usermod can subscribe)
virtual bool onMqttMessage(char* topic, char* payload) { return false; } // fired upon MQTT message received (wled topic)
virtual bool onEspNowMessage(uint8_t* sender, uint8_t* payload, uint8_t len) { return false; } // fired upon ESP-NOW message received
virtual bool onUdpPacket(uint8_t* payload, uint8_t len) { return false; } //fired upon UDP packet received
virtual void onUpdateBegin(bool) {} // fired prior to and after unsuccessful firmware update
virtual void onStateChange(uint8_t mode) {} // fired upon WLED state change
virtual uint16_t getId() {return USERMOD_ID_UNSPECIFIED;}
@@ -481,6 +482,7 @@ namespace UsermodManager {
#ifndef WLED_DISABLE_ESPNOW
bool onEspNowMessage(uint8_t* sender, uint8_t* payload, uint8_t len);
#endif
bool onUdpPacket(uint8_t* payload, uint8_t len);
void onUpdateBegin(bool);
void onStateChange(uint8_t);
Usermod* lookup(uint16_t mod_id);

View File

@@ -557,6 +557,9 @@ void handleNotifications()
return;
}
// usermods hook can override processing
if (UsermodManager::onUdpPacket(udpIn, packetSize)) return;
//wled notifier, ignore if realtime packets active
if (udpIn[0] == 0 && !realtimeMode && receiveGroups)
{

View File

@@ -68,6 +68,10 @@ bool UsermodManager::onEspNowMessage(uint8_t* sender, uint8_t* payload, uint8_t
return false;
}
#endif
bool UsermodManager::onUdpPacket(uint8_t* payload, uint8_t len) {
for (auto mod = _usermod_table_begin; mod < _usermod_table_end; ++mod) if ((*mod)->onUdpPacket(payload, len)) return true;
return false;
}
void UsermodManager::onUpdateBegin(bool init) { for (auto mod = _usermod_table_begin; mod < _usermod_table_end; ++mod) (*mod)->onUpdateBegin(init); } // notify usermods that update is to begin
void UsermodManager::onStateChange(uint8_t mode) { for (auto mod = _usermod_table_begin; mod < _usermod_table_end; ++mod) (*mod)->onStateChange(mode); } // notify usermods that WLED state changed