feat: local ctrl

Author: kakopappa

README.md

@@ -150,6 +150,77 @@ mySwitch.sendPushNotification("Hello SinricPro!");
 * [Settings](https://github.com/sinricpro/esp8266-esp32-sdk/tree/master/examples/Settings)
 ---
 
+## Local Control (LAN/UDP)
+
+Starting with SDK v4.2.0, SinricPro devices can be controlled directly on the
+local network without a cloud round-trip.  When the mobile app cannot reach the
+cloud within its timeout window, or when the user has selected "Local-first"
+mode, the app sends a signed UDP command directly to the device IP address and
+port.  The same HMAC-SHA256 credentials used for cloud communication are reused
+for authentication — no separate provisioning step is needed.
+
+### What it is
+
+A UDP listener bound to the multicast group `224.9.9.9:3333` (also responds to
+unicast to the device IP on the same port).  Incoming commands use exactly the
+same JSON payload shape as cloud WebSocket commands and are dispatched through
+the same capability callbacks (`onPowerState`, `onBrightness`, etc.).
+
+### What changes for sketch authors
+
+Nothing.  Existing callback registrations work for both cloud and LAN commands
+automatically.  Local control is on by default.
+
+### What changes for app developers
+
+LAN availability is signaled implicitly: the app gates local-control on the
+device reporting a non-empty `deviceIp` in the cloud model combined with an SDK
+version >= 4.2.0.  No additional headers are required.  After a successful LAN
+command the app posts the new state to `POST /api/v1/devices/:id/state` so the
+cloud and other clients stay in sync — the firmware does not echo UDP responses
+to the WebSocket.
+
+### Compile-time flags
+
+| Flag | Effect |
+|---|---|
+| `SINRICPRO_NOMDNS` | Disable the mDNS service announcement while keeping UDP active. |
+
+Define this flag before including `SinricPro.h`, or pass it as a compiler
+flag (`-DSINRICPRO_NOMDNS`) in `platformio.ini` / Arduino IDE build flags.
+
+### Network requirements
+
+- The phone and device must be on the same LAN segment (or a routed LAN that
+  passes multicast and allows unicast to device IP:3333).
+- UDP multicast is required only for mDNS-based discovery; unicast commands use
+  the device IP reported by the cloud (`Device.lan.ip`).
+- Port 3333 UDP must not be firewalled between the phone and the device.
+- Enterprise or guest WiFi networks that block multicast/mDNS will fall back to
+  the cloud-reported IP automatically.
+
+### Security model
+
+All UDP commands are signed with HMAC-SHA256 using the same `APP_SECRET` as
+cloud commands.  The firmware verifies the signature before dispatching.
+
+### mDNS service record
+
+When `SINRICPRO_NOMDNS` is not defined the SDK announces:
+
+```
+Service type : _sinricpro._udp.local.
+Port         : 3333
+TXT records  : deviceIds=<comma-separated device IDs>
+               sdk=<SDK version, e.g. "4.2.0">
+               udp=1
+```
+
+Browse with `dns-sd -B _sinricpro._udp` (macOS) or
+`avahi-browse -r _sinricpro._udp` (Linux) to discover devices.
+
+---
+
 ## Licensing and Credits
 * The Arduino IDE is developed and maintained by the Arduino team. The IDE is licensed under GPL.
 * [ArduinoJson](https://github.com/bblanchon/ArduinoJson) is licensed under the MIT.

changelog.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## Version 4.2.0
+
+### New — Local Control (LAN/UDP)
+
+1. **Completed UDP local-control path** — Commands sent directly to the device 
+   over the LAN are now fully dispatched through the same capability handlers 
+   as cloud commands. No sketch changes are required; existing `onPowerState`, 
+   `onBrightness`, etc. callbacks work for both cloud and LAN commands.
+
+2. **Fixed multicast re-bind bug** (`SinricProUDP.h`).
+   - ESP32: removed the unnecessary post-`endPacket()` `beginMulticast()` call.
+     The underlying IDF socket correctly retains multicast group membership
+     after a unicast send; the re-bind was harmless but wasteful.
+   - ESP8266: introduced a dedicated TX socket (`WiFiUDP _udpTx`) so the
+     multicast RX socket is never closed during a reply.  The previous code
+     called `endPacket()` on the multicast socket and then `beginMulticast()`
+     again; some SDK versions unbind the socket from the multicast group on
+     `endPacket()`, silently dropping all subsequent incoming packets.
+
+3. **Compile-time gate** — `SINRICPRO_NOMDNS` — define before including
+   `SinricPro.h` to disable the mDNS service announcement while keeping UDP
+   control active.
+
+4. **mDNS service announcement** (`SinricProMDNS.h`, new file) — the SDK
+   registers `_sinricpro._udp.local.` on `UDP_MULTICAST_PORT` (3333) with TXT
+   records `deviceIds=<csv>`, `sdk=<version>`, `udp=1`.  The record is updated
+   each time the WebSocket reconnects so DHCP renewals are automatically
+   reflected.  Gate with `SINRICPRO_NOMDNS`.
+
+### Behavior change
+
+- **Cloud echo suppressed for `IF_UDP` requests** — when a command arrives over
+  UDP the response is sent back over UDP only.  The response is no longer also
+  forwarded to the cloud via WebSocket.  The mobile app is responsible for
+  posting the new state that the cloud and other clients stay in sync.  Users on the
+  cloud path are unaffected.
+
 ## Version 4.1.0
   New: 
   1. The `sendSettingEvent` method has been added to SettingController.

src/SinricPro.h

@@ -15,10 +15,11 @@
 #include "SinricProQueue.h"
 #include "SinricProSignature.h"
 #include "SinricProStrings.h"
-#include "SinricProUDP.h"
 #include "SinricProWebsocket.h"
 #include "Timestamp.h"
 #include "EventLimiter.h"
+#include "SinricProUDP.h"
+#include "SinricProMDNS.h"
 namespace SINRICPRO_NAMESPACE {
 
 /**
@@ -144,6 +145,8 @@ class SinricProClass : public SinricProInterface {
 
     SinricProDeviceInterface* getDevice(String deviceId);
 
+    String joinDeviceIds(char separator);
+
     template <typename DeviceType>
     DeviceType& getDeviceInstance(String deviceId);
 
@@ -155,6 +158,7 @@ class SinricProClass : public SinricProInterface {
 
     WebsocketListener _websocketListener;
     UdpListener       _udpListener;
+    SinricProMDNS     _mdnsListener;
     SinricProQueue_t  receiveQueue;
     SinricProQueue_t  sendQueue;
 
@@ -262,6 +266,14 @@ void SinricProClass::begin(String appKey, String appSecret, String serverURL) {
     this->serverURL = serverURL;
     _begin          = true;
     _udpListener.begin(&receiveQueue);
+#ifndef SINRICPRO_NOMDNS
+    {
+        String hostName = "sinricpro-" + WiFi.macAddress();
+        hostName.replace(":", "");
+        hostName.toLowerCase();
+        _mdnsListener.begin(hostName, joinDeviceIds(',')); //mDNS TXT uses ',' (CSV).
+    }
+#endif
 }
 
 template <typename DeviceType>
@@ -322,6 +334,9 @@ void SinricProClass::handle() {
     if (!isConnected()) connect();
     _websocketListener.handle();
     _udpListener.handle();
+#ifndef SINRICPRO_NOMDNS
+    _mdnsListener.handle();
+#endif
 
     handleReceiveQueue();
     handleSendQueue();
@@ -484,7 +499,6 @@ void SinricProClass::handleInvalidSignatureRequest(JsonDocument& requestMessage,
 }
 
 void SinricProClass::handleSendQueue() {
-    if (!isConnected()) return;
     if (!timestamp.getTimestamp()) return;
     while (sendQueue.size() > 0) {
         DEBUG_SINRIC("[SinricPro:handleSendQueue()]: %i message(s) in sendQueue\r\n", sendQueue.size());
@@ -508,8 +522,12 @@ void SinricProClass::handleSendQueue() {
 
         switch (rawMessage->getInterface()) {
             case IF_WEBSOCKET:
-                DEBUG_SINRIC("[SinricPro:handleSendQueue]: Sending to websocket\r\n");
-                _websocketListener.sendMessage(messageStr);
+                if (isConnected()) {
+                    DEBUG_SINRIC("[SinricPro:handleSendQueue]: Sending to websocket\r\n");
+                    _websocketListener.sendMessage(messageStr);
+                } else {
+                    DEBUG_SINRIC("[SinricPro:handleSendQueue]: Dropping WS message — not connected\r\n");
+                }
                 break;
             case IF_UDP:
                 DEBUG_SINRIC("[SinricPro:handleSendQueue]: Sending to UDP\r\n");
@@ -523,17 +541,24 @@ void SinricProClass::handleSendQueue() {
     }
 }
 
-void SinricProClass::connect() {
-    String deviceList;
-    int    i = 0;
+String SinricProClass::joinDeviceIds(char separator) {
+    String out;
+    int i = 0;
     for (auto& device : devices) {
-        String deviceId = device->getDeviceId();
-        if (i > 0) deviceList += ';';
-        deviceList += device->getDeviceId();
-        i++;
+        if (i++ > 0) out += separator;
+        out += device->getDeviceId();
     }
+    return out;
+}
 
-    _websocketListener.begin(serverURL, appKey, deviceList, &receiveQueue);
+void SinricProClass::connect() {
+    _websocketListener.begin(serverURL, appKey, joinDeviceIds(';'), &receiveQueue);
+
+#ifndef SINRICPRO_NOMDNS
+    // Refresh mDNS TXT record on each (re-)connect so additions between
+    // begin() and connect() are reflected.  mDNS TXT uses ',' (CSV).
+    _mdnsListener.update(joinDeviceIds(','));
+#endif
 }
 
 void SinricProClass::stop() {

src/SinricProConfig.h

@@ -6,7 +6,7 @@
  */
 
 #pragma once
-/* 
+/*
  * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  * !!                                                 !!
  * !!             WARNING: DON'T TOUCH !              !!
@@ -18,8 +18,6 @@
  * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  */
 
-#pragma once
-
 // Server Configuration
 #ifndef SINRICPRO_NOSSL
 #define WEBSOCKET_SSL
@@ -58,6 +56,10 @@
 #define UDP_MULTICAST_PORT 3333
 #endif
 
+#ifndef SINRICPRO_NOMDNS
+  #define SINRICPRO_MDNS_ENABLED
+#endif
+
 // WebSocket Configuration
 #ifdef DEBUG_WIFI_ISSUE
   #define WEBSOCKET_PING_INTERVAL 10000

src/SinricProMDNS.h

@@ -0,0 +1,102 @@
+/*
+ *  Copyright (c) 2019 Sinric. All rights reserved.
+ *  Licensed under Creative Commons Attribution-Share Alike (CC BY-SA)
+ *
+ *  This file is part of the Sinric Pro (https://github.com/sinricpro/)
+ */
+
+#pragma once
+
+#include "SinricProConfig.h"
+
+#ifdef SINRICPRO_MDNS_ENABLED
+
+#if defined(ESP8266)
+  #include <ESP8266WiFi.h>
+  #include <ESP8266mDNS.h>
+#elif defined(ESP32)
+  #include <WiFi.h>
+  #include <ESPmDNS.h>
+#endif
+
+#include "SinricProVersion.h"
+#include "SinricProNamespace.h"
+#include "SinricProDebug.h"
+
+namespace SINRICPRO_NAMESPACE {
+
+/**
+ * @brief Announces this device on the LAN via mDNS.
+ *
+ * Service: _sinricpro._udp.local.  on UDP_MULTICAST_PORT.
+ * TXT records:
+ *   deviceIds  — semicolon-separated list of registered device IDs
+ *   sdk        — SDK version string (e.g. "4.2.0")
+ *   udp        — always "1"
+ *
+ * Gate with SINRICPRO_NOMDNS to remove entirely.
+ *
+ * Call begin() once after WiFi is connected and MDNS.begin() has been called
+ * by user code (or it will be called internally here).
+ * Call update() whenever the device list changes (e.g. after adding a device).
+ */
+class SinricProMDNS {
+  public:
+    void begin(const String& hostName, const String& deviceIds);
+    void update(const String& deviceIds);
+    void handle();
+  private:
+    bool _announced = false;
+    void announce(const String& deviceIds);
+};
+
+void SinricProMDNS::begin(const String& hostName, const String& deviceIds) {
+#if defined(ESP8266)
+    // On ESP8266, MDNS.begin() must be called with the desired hostname.
+    // If user code already called it, calling again is harmless.
+    MDNS.begin(hostName.c_str());
+#elif defined(ESP32)
+    MDNS.begin(hostName.c_str());
+#endif
+    announce(deviceIds);
+}
+
+void SinricProMDNS::announce(const String& deviceIds) {
+    // Remove any existing SinricPro service record before re-adding so that
+    // the TXT record reflects the current device list.
+    if (_announced) {
+#if defined(ESP8266)
+        // ESP8266mDNS 3.x: removeService(instance, service, protocol)
+        // Passing nullptr as instance removes the default (unnamed) instance.
+        MDNS.removeService(nullptr, "sinricpro", "udp");
+#elif defined(ESP32)
+        // ESPmDNS on ESP32 does not expose removeService; restart the responder.
+        // The service port and hostname are small so this is fast.
+        MDNS.end();
+        MDNS.begin(WiFi.getHostname());
+#endif
+    }
+
+    MDNS.addService("sinricpro", "udp", UDP_MULTICAST_PORT);
+    MDNS.addServiceTxt("sinricpro", "udp", "deviceIds", deviceIds.c_str());
+    MDNS.addServiceTxt("sinricpro", "udp", "sdk",       SINRICPRO_VERSION);
+    MDNS.addServiceTxt("sinricpro", "udp", "udp",       "1");
+    _announced = true;
+    DEBUG_SINRIC("[SinricPro:mDNS]: announced _sinricpro._udp.local. port=%d deviceIds=%s\r\n",
+                 UDP_MULTICAST_PORT, deviceIds.c_str());
+}
+
+void SinricProMDNS::update(const String& deviceIds) {
+    announce(deviceIds);
+}
+
+void SinricProMDNS::handle() {
+#if defined(ESP8266)
+    MDNS.update();
+#endif
+    // On ESP32 the mDNS stack runs in a FreeRTOS task; no polling needed.
+}
+
+} // SINRICPRO_NAMESPACE
+
+#endif // SINRICPRO_MDNS_ENABLED

src/SinricProSignature.cpp

@@ -8,6 +8,7 @@
 #include <WString.h>
 #include <ArduinoJson.h>
 #include "SinricProSignature.h"
+#include "SinricProDebug.h"
 
 #if defined (ESP8266) || defined(ARDUINO_ARCH_RP2040)
   #include <bearssl/bearssl_hmac.h>