Merge pull request #437 from sinricpro/4.0-dev

feat: `sendSettingEvent` method has been added to SettingController.

Author: kakopappa

changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Version 4.1.0
+  New: 
+  1. The `sendSettingEvent` method has been added to SettingController.
+
+    Example Usage:
+
+    ```cpp
+    // for device
+    SinricProSwitch& mySwitch = SinricPro[SWITCH_ID];
+    mySwitch.sendSettingEvent("brightness", 75); // Send int setting
+
+    // for module
+    int rssi = WiFi.RSSI();
+    SinricPro.sendSettingEvent('wifi_rssi', rssi);
+    ```
+
+  2. Validate APP_KEY, APP_SECRET, DEVICE_ID
+
+
 ## Version 4.0.0
 
 - **BREAKING CHANGE**: Updated the callback signature in `SettingController.h` to use the `SettingValue` class instead of `String` for setting values. 

library.json

@@ -18,7 +18,7 @@
     }
   ],
   "homepage": "https://sinric.pro",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "frameworks": "arduino",
   "platforms": ["espressif8266", "espressif32", "raspberrypi"],
   "dependencies": [

library.properties

@@ -1,5 +1,5 @@
 name=SinricPro
-version=4.0.0
+version=4.1.0
 author=Boris Jaeger <sivar2311@gmail.com>
 maintainer=Boris Jaeger <sivar2311@gmail.com>
 sentence=Library for https://sinric.pro - simple way to connect your device to alexa

src/Capabilities/SettingController.h

@@ -4,6 +4,7 @@
 
 #include "../SinricProRequest.h"
 #include "../SinricProStrings.h"
+#include "../EventLimiter.h"
 
 #include "../SinricProNamespace.h"
 namespace SINRICPRO_NAMESPACE {
@@ -24,16 +25,19 @@ class SettingController {
   public:
     SettingController();
     void onSetSetting(SetSettingCallback cb);
+    bool sendSettingEvent(String settingId, SettingValue settingValue, String cause = FSTR_SINRICPRO_PHYSICAL_INTERACTION);
 
   protected:
     bool handleSettingController(SinricProRequest &request);
 
   private:
+    EventLimiter event_limiter;
     SetSettingCallback setSettingCallback;
 };
 
 template <typename T>
-SettingController<T>::SettingController() {
+SettingController<T>::SettingController()
+: event_limiter(EVENT_LIMIT_STATE) {
   T* device = static_cast<T*>(this);
   device->registerRequestHandler(std::bind(&SettingController<T>::handleSettingController, this, std::placeholders::_1));
 }
@@ -43,6 +47,39 @@ void SettingController<T>::onSetSetting(SetSettingCallback cb) {
   setSettingCallback = cb;
 }
 
+/**
+ * @brief Send `setSetting` event to SinricPro Server
+ *
+ * @param settingId   `String` the setting identifier
+ * @param settingValue `SettingValue` (int, float, bool, or String) the setting value
+ * @param cause       (optional) `String` reason why event is sent (default = `"PHYSICAL_INTERACTION"`)
+ * @return the success of sending the event
+ * @retval true   event has been sent successfully
+ * @retval false  event has not been sent, maybe you sent too many events in a short distance of time
+ **/
+template <typename T>
+bool SettingController<T>::sendSettingEvent(String settingId, SettingValue settingValue, String cause) {
+  if (event_limiter) return false;
+  T* device = static_cast<T*>(this);
+
+  JsonDocument eventMessage = device->prepareEvent(FSTR_SETTING_setSetting, cause.c_str());
+  JsonObject event_value = eventMessage[FSTR_SINRICPRO_payload][FSTR_SINRICPRO_value];
+  eventMessage[FSTR_SINRICPRO_scope] = FSTR_SINRICPRO_device;
+  event_value[FSTR_SETTING_id] = settingId;
+
+  if (std::holds_alternative<int>(settingValue)) {
+    event_value[FSTR_SETTING_value] = std::get<int>(settingValue);
+  } else if (std::holds_alternative<float>(settingValue)) {
+    event_value[FSTR_SETTING_value] = std::get<float>(settingValue);
+  } else if (std::holds_alternative<bool>(settingValue)) {
+    event_value[FSTR_SETTING_value] = std::get<bool>(settingValue);
+  } else if (std::holds_alternative<String>(settingValue)) {
+    event_value[FSTR_SETTING_value] = std::get<String>(settingValue);
+  }
+
+  return device->sendEvent(eventMessage);
+}
+
 template <typename T>
 bool SettingController<T>::handleSettingController(SinricProRequest &request) {
   T* device = static_cast<T*>(this);

src/SinricPro.h

@@ -18,6 +18,7 @@
 #include "SinricProUDP.h"
 #include "SinricProWebsocket.h"
 #include "Timestamp.h"
+#include "EventLimiter.h"
 namespace SINRICPRO_NAMESPACE {
 
 /**
@@ -108,6 +109,7 @@ class SinricProClass : public SinricProInterface {
     void           onOTAUpdate(OTAUpdateCallbackHandler cb);
     void           onSetSetting(SetSettingCallbackHandler cb);
     void           onReportHealth(ReportHealthCallbackHandler cb);
+    bool           sendSettingEvent(String settingId, SettingValue settingValue, String cause = FSTR_SINRICPRO_PHYSICAL_INTERACTION);
 
   protected:
     template <typename DeviceType>
@@ -162,6 +164,7 @@ class SinricProClass : public SinricProInterface {
     String responseMessageStr = "";
 
     SinricProModuleCommandHandler _moduleCommandHandler;
+    EventLimiter _settingEventLimiter{EVENT_LIMIT_STATE};
 };
 
 class SinricProClass::Proxy {
@@ -225,12 +228,27 @@ DeviceType& SinricProClass::getDeviceInstance(String deviceId) {
  **/
 void SinricProClass::begin(String appKey, String appSecret, String serverURL) {
     bool success = true;
-    if (!appKey.length()) {
-        DEBUG_SINRIC("[SinricPro:begin()]: App-Key \"%s\" is invalid!! Please check your app-key!! SinricPro will not work!\r\n", appKey.c_str());
+
+    // Validate APP_KEY
+    // - Must be 36 characters
+    // - UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    if (appKey.length() != 36) {
+        Serial.printf("[SinricPro:begin()]: Invalid App Key '%s' detected (Length: %d; Expected: 36). Initialization aborted! Please check your SinricPro credentials.\r\n", appKey.c_str(), appKey.length());
+        success = false;
+    } else if (appKey.charAt(8) != '-' || appKey.charAt(13) != '-' || appKey.charAt(18) != '-' || appKey.charAt(23) != '-') {
+        Serial.printf("[SinricPro:begin()]: App Key '%s' is in an invalid format. Initialization aborted!\r\n", appKey.c_str());
         success = false;
     }
-    if (!appSecret.length()) {
-        DEBUG_SINRIC("[SinricPro:begin()]: App-Secret \"%s\" is invalid!! Please check your app-secret!! SinricPro will not work!\r\n", appSecret.c_str());
+
+    // Validate APP_SECRET (73 characters)
+    // - Must be 73 characters
+    // - Double UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    if (appSecret.length() != 73) {
+        Serial.printf("[SinricPro:begin()]: Invalid App Secret '%s' detected (Length: %d; Expected: 73). Initialization aborted! Please check your SinricPro credentials.\r\n", appSecret.c_str(), appSecret.length());
+        success = false;
+    } else if (appSecret.charAt(8) != '-' || appSecret.charAt(13) != '-' || appSecret.charAt(18) != '-' || appSecret.charAt(23) != '-' ||
+               appSecret.charAt(36) != '-' || appSecret.charAt(45) != '-' || appSecret.charAt(50) != '-' || appSecret.charAt(55) != '-' || appSecret.charAt(60) != '-') {
+        Serial.printf("[SinricPro:begin()]: App Secret '%s' is in an invalid format. Initialization aborted!\r\n", appSecret.c_str());
         success = false;
     }
 
@@ -248,6 +266,14 @@ void SinricProClass::begin(String appKey, String appSecret, String serverURL) {
 
 template <typename DeviceType>
 DeviceType& SinricProClass::add(String deviceId) {
+    // Validate DEVICE_ID
+    // - Must be 24 characters
+    // - Hexadecimal only (0-9, a-f, A-F)
+    // - Format: 695b4624f6e5944047661b8a
+    if (deviceId.length() != 24) {
+        Serial.printf("[SinricPro:add()]: Device Id \"%s\" is invalid (wrong length: expected 24, got %d)!! Please check your device-id!!\r\n", deviceId.c_str(), deviceId.length());
+    }
+
     DeviceType* newDevice = new DeviceType(deviceId);
     DEBUG_SINRIC("[SinricPro:add()]: Adding device with id \"%s\".\r\n", deviceId.c_str());
     newDevice->begin(this);
@@ -564,6 +590,42 @@ void SinricProClass::onReportHealth(ReportHealthCallbackHandler cb) {
     _moduleCommandHandler.onReportHealth(cb);
 }
 
+/**
+ * @brief Send `setSetting` event to SinricPro Server at module level
+ *
+ * @param settingId   `String` the setting identifier
+ * @param settingValue `SettingValue` (int, float, bool, or String) the setting value
+ * @param cause       (optional) `String` reason why event is sent (default = `"PHYSICAL_INTERACTION"`)
+ * @return the success of sending the event
+ * @retval true   event has been sent successfully
+ * @retval false  event has not been sent, maybe you sent too many events in a short distance of time
+ **/
+bool SinricProClass::sendSettingEvent(String settingId, SettingValue settingValue, String cause) {
+    if (_settingEventLimiter) return false;
+
+    JsonDocument eventMessage = prepareEvent("", FSTR_SETTING_setSetting, cause.c_str());
+    JsonObject payload = eventMessage[FSTR_SINRICPRO_payload];
+
+    payload.remove(FSTR_SINRICPRO_deviceId);
+    payload[FSTR_SINRICPRO_scope] = FSTR_SINRICPRO_module;
+
+    JsonObject event_value = payload[FSTR_SINRICPRO_value];
+    event_value[FSTR_SETTING_id] = settingId;
+
+    if (std::holds_alternative<int>(settingValue)) {
+        event_value[FSTR_SETTING_value] = std::get<int>(settingValue);
+    } else if (std::holds_alternative<float>(settingValue)) {
+        event_value[FSTR_SETTING_value] = std::get<float>(settingValue);
+    } else if (std::holds_alternative<bool>(settingValue)) {
+        event_value[FSTR_SETTING_value] = std::get<bool>(settingValue);
+    } else if (std::holds_alternative<String>(settingValue)) {
+        event_value[FSTR_SETTING_value] = std::get<String>(settingValue);
+    }
+
+    sendMessage(eventMessage);
+    return true;
+}
+
 /**
  * @brief Set callback function for websocket connected event
  *

src/SinricProVersion.h

@@ -5,7 +5,7 @@
 
 // Version Configuration
 #define SINRICPRO_VERSION_MAJOR     4
-#define SINRICPRO_VERSION_MINOR     0
+#define SINRICPRO_VERSION_MINOR     1
 #define SINRICPRO_VERSION_REVISION  0
 #define SINRICPRO_VERSION STR(SINRICPRO_VERSION_MAJOR) "." STR(SINRICPRO_VERSION_MINOR) "." STR(SINRICPRO_VERSION_REVISION)
 #define SINRICPRO_VERSION_STR "SinricPro (v" SINRICPRO_VERSION ")"