Add raw commands service (v0.2.13)

- Add 'Allow Raw Commands' config option (off by default)
- Add novastar_h.send_raw_command service for raw API access
- Service requires host, endpoint, and JSON body parameters

Author: Ted Roberts

custom_components/novastar_h/__init__.py

@@ -3,17 +3,21 @@
 import logging
 from typing import Any
 
+import voluptuous as vol
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import CONF_HOST, CONF_PORT
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, ServiceCall
+import homeassistant.helpers.config_validation as cv
 
 from .api import NovastarClient
 from .const import (
+    CONF_ALLOW_RAW_COMMANDS,
     CONF_DEVICE_ID,
     CONF_ENCRYPTION,
     CONF_PROJECT_ID,
     CONF_SCREEN_ID,
     CONF_SECRET_KEY,
+    DEFAULT_ALLOW_RAW_COMMANDS,
     DEFAULT_DEVICE_ID,
     DEFAULT_ENCRYPTION,
     DEFAULT_PORT,
@@ -26,6 +30,18 @@
 
 _LOGGER = logging.getLogger(__name__)
 
+SERVICE_SEND_RAW_COMMAND = "send_raw_command"
+ATTR_ENDPOINT = "endpoint"
+ATTR_BODY = "body"
+
+SERVICE_SEND_RAW_COMMAND_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_HOST): cv.string,
+        vol.Required(ATTR_ENDPOINT): cv.string,
+        vol.Required(ATTR_BODY): dict,
+    }
+)
+
 
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up Novastar H Series from a config entry."""
@@ -56,6 +72,47 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         "device_info": device_info,
     }
 
+    # Register send_raw_command service if enabled and not already registered
+    if entry.data.get(CONF_ALLOW_RAW_COMMANDS, DEFAULT_ALLOW_RAW_COMMANDS):
+        if not hass.services.has_service(DOMAIN, SERVICE_SEND_RAW_COMMAND):
+            async def async_send_raw_command(call: ServiceCall) -> None:
+                """Handle send_raw_command service call."""
+                host = call.data[CONF_HOST]
+                endpoint = call.data[ATTR_ENDPOINT]
+                body = call.data[ATTR_BODY]
+
+                # Find the client for the specified host
+                client_found = None
+                for eid, data in hass.data[DOMAIN].items():
+                    if isinstance(data, dict) and "client" in data:
+                        if data["client"].host == host:
+                            # Check if this entry allows raw commands
+                            config_entry = hass.config_entries.async_get_entry(eid)
+                            if config_entry and config_entry.data.get(
+                                CONF_ALLOW_RAW_COMMANDS, DEFAULT_ALLOW_RAW_COMMANDS
+                            ):
+                                client_found = data["client"]
+                                break
+
+                if not client_found:
+                    _LOGGER.error(
+                        "No Novastar device found at %s with raw commands enabled", host
+                    )
+                    return
+
+                result = await client_found.async_send_raw_command(endpoint, body)
+                if result is None:
+                    _LOGGER.warning("Raw command to %s failed", endpoint)
+                else:
+                    _LOGGER.debug("Raw command result: %s", result)
+
+            hass.services.async_register(
+                DOMAIN,
+                SERVICE_SEND_RAW_COMMAND,
+                async_send_raw_command,
+                schema=SERVICE_SEND_RAW_COMMAND_SCHEMA,
+            )
+
     loaded_platforms: list[Any] = []
     for platform in PLATFORMS:
         try:

custom_components/novastar_h/api.py

@@ -444,3 +444,17 @@ async def async_get_device_status_info(
                     if signal_status is not None and isinstance(signal_status, (int, float)):
                         result["signal_status"] = int(signal_status)
         return result
+
+    async def async_send_raw_command(
+        self, endpoint: str, body: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Send a raw API command.
+
+        Args:
+            endpoint: API endpoint path (e.g., "device/readDetail")
+            body: Business data for the request body
+
+        Returns:
+            Response body dict on success, None on failure
+        """
+        return await self._async_request(endpoint, body)

custom_components/novastar_h/config_flow.py

@@ -11,9 +11,11 @@
 
 from .api import NovastarClient
 from .const import (
+    CONF_ALLOW_RAW_COMMANDS,
     CONF_ENCRYPTION,
     CONF_PROJECT_ID,
     CONF_SECRET_KEY,
+    DEFAULT_ALLOW_RAW_COMMANDS,
     DEFAULT_ENCRYPTION,
     DEFAULT_NAME,
     DEFAULT_PORT,
@@ -49,6 +51,7 @@ async def async_step_user(
             project_id = user_input[CONF_PROJECT_ID]
             secret_key = user_input[CONF_SECRET_KEY]
             encryption = user_input.get(CONF_ENCRYPTION, DEFAULT_ENCRYPTION)
+            allow_raw_commands = user_input.get(CONF_ALLOW_RAW_COMMANDS, DEFAULT_ALLOW_RAW_COMMANDS)
 
             # Validate credentials by testing connection
             client = NovastarClient(
@@ -71,6 +74,7 @@ async def async_step_user(
                         CONF_PROJECT_ID: project_id,
                         CONF_SECRET_KEY: secret_key,
                         CONF_ENCRYPTION: encryption,
+                        CONF_ALLOW_RAW_COMMANDS: allow_raw_commands,
                     },
                 )
             errors["base"] = "cannot_connect"
@@ -84,6 +88,7 @@ async def async_step_user(
                     vol.Required(CONF_PROJECT_ID): str,
                     vol.Required(CONF_SECRET_KEY): str,
                     vol.Optional(CONF_ENCRYPTION, default=DEFAULT_ENCRYPTION): bool,
+                    vol.Optional(CONF_ALLOW_RAW_COMMANDS, default=DEFAULT_ALLOW_RAW_COMMANDS): bool,
                     vol.Optional(CONF_NAME, default=DEFAULT_NAME): str,
                 }
             ),
@@ -151,6 +156,7 @@ async def async_step_manual(
             project_id = user_input[CONF_PROJECT_ID]
             secret_key = user_input[CONF_SECRET_KEY]
             encryption = user_input.get(CONF_ENCRYPTION, DEFAULT_ENCRYPTION)
+            allow_raw_commands = user_input.get(CONF_ALLOW_RAW_COMMANDS, DEFAULT_ALLOW_RAW_COMMANDS)
 
             # Validate credentials by testing connection
             client = NovastarClient(
@@ -173,6 +179,7 @@ async def async_step_manual(
                         CONF_PROJECT_ID: project_id,
                         CONF_SECRET_KEY: secret_key,
                         CONF_ENCRYPTION: encryption,
+                        CONF_ALLOW_RAW_COMMANDS: allow_raw_commands,
                     },
                 )
             errors["base"] = "cannot_connect"
@@ -186,6 +193,7 @@ async def async_step_manual(
                     vol.Required(CONF_PROJECT_ID): str,
                     vol.Required(CONF_SECRET_KEY): str,
                     vol.Optional(CONF_ENCRYPTION, default=DEFAULT_ENCRYPTION): bool,
+                    vol.Optional(CONF_ALLOW_RAW_COMMANDS, default=DEFAULT_ALLOW_RAW_COMMANDS): bool,
                     vol.Optional(CONF_NAME, default=DEFAULT_NAME): str,
                 }
             ),
@@ -225,6 +233,7 @@ async def async_step_credentials(
                         CONF_PROJECT_ID: project_id,
                         CONF_SECRET_KEY: secret_key,
                         CONF_ENCRYPTION: encryption,
+                        CONF_ALLOW_RAW_COMMANDS: DEFAULT_ALLOW_RAW_COMMANDS,
                     },
                 )
             errors["base"] = "cannot_connect"
@@ -332,6 +341,7 @@ async def async_step_discovery_confirm(
                         CONF_PROJECT_ID: project_id,
                         CONF_SECRET_KEY: secret_key,
                         CONF_ENCRYPTION: encryption,
+                        CONF_ALLOW_RAW_COMMANDS: DEFAULT_ALLOW_RAW_COMMANDS,
                     },
                 )
             errors["base"] = "cannot_connect"

custom_components/novastar_h/const.py

@@ -13,10 +13,12 @@
 CONF_PROJECT_ID = "project_id"
 CONF_SECRET_KEY = "secret_key"
 CONF_ENCRYPTION = "encryption"
+CONF_ALLOW_RAW_COMMANDS = "allow_raw_commands"
 
 DEFAULT_DEVICE_ID = 0
 DEFAULT_SCREEN_ID = 0
 DEFAULT_ENCRYPTION = False
+DEFAULT_ALLOW_RAW_COMMANDS = False
 
 PLATFORMS: list[Platform] = [
     Platform.SWITCH,

custom_components/novastar_h/manifest.json

@@ -21,5 +21,5 @@
     }
   ],
   "zeroconf": ["_novastar._tcp.local."],
-  "version": "0.2.12"
+  "version": "0.2.13"
 }

custom_components/novastar_h/services.yaml

@@ -0,0 +1,25 @@
+send_raw_command:
+  name: Send Raw Command
+  description: Send a raw API command to the Novastar processor (requires "Allow Raw Commands" option in configuration).
+  fields:
+    host:
+      name: Host
+      description: The IP address of the Novastar processor to send the command to.
+      required: true
+      example: "192.168.1.100"
+      selector:
+        text:
+    endpoint:
+      name: Endpoint
+      description: The API endpoint path (e.g., "device/readDetail", "screen/writeBrightness").
+      required: true
+      example: "device/readDetail"
+      selector:
+        text:
+    body:
+      name: Body
+      description: The JSON body to send with the request.
+      required: true
+      example: '{"deviceId": 0}'
+      selector:
+        object:

custom_components/novastar_h/strings.json

@@ -10,14 +10,16 @@
           "project_id": "Project ID",
           "secret_key": "Secret Key",
           "encryption": "Enable Encryption",
+          "allow_raw_commands": "Allow Raw Commands",
           "name": "Name"
         },
         "data_description": {
           "host": "IP address of your Novastar processor",
           "port": "API port (default: 8000)",
           "project_id": "From Settings > OpenAPI Management on your device",
           "secret_key": "From Settings > OpenAPI Management on your device",
-          "encryption": "Enable encrypted communication with the device"
+          "encryption": "Enable encrypted communication with the device",
+          "allow_raw_commands": "Enable sending raw API commands via service call"
         }
       },
       "scan": {
@@ -36,14 +38,16 @@
           "project_id": "Project ID",
           "secret_key": "Secret Key",
           "encryption": "Enable Encryption",
+          "allow_raw_commands": "Allow Raw Commands",
           "name": "Name"
         },
         "data_description": {
           "host": "IP address of your Novastar processor",
           "port": "API port (default: 8000)",
           "project_id": "From Settings > OpenAPI Management on your device",
           "secret_key": "From Settings > OpenAPI Management on your device",
-          "encryption": "Enable encrypted communication with the device"
+          "encryption": "Enable encrypted communication with the device",
+          "allow_raw_commands": "Enable sending raw API commands via service call"
         }
       },
       "credentials": {
@@ -115,5 +119,25 @@
         "name": "Signal Power Status"
       }
     }
+  },
+  "services": {
+    "send_raw_command": {
+      "name": "Send Raw Command",
+      "description": "Send a raw API command to the Novastar processor (requires 'Allow Raw Commands' option).",
+      "fields": {
+        "host": {
+          "name": "Host",
+          "description": "The IP address of the Novastar processor."
+        },
+        "endpoint": {
+          "name": "Endpoint",
+          "description": "The API endpoint path (e.g., 'device/readDetail')."
+        },
+        "body": {
+          "name": "Body",
+          "description": "The JSON body to send with the request."
+        }
+      }
+    }
   }
 }

custom_components/novastar_h/translations/en.json

@@ -10,14 +10,16 @@
           "project_id": "Project ID",
           "secret_key": "Secret Key",
           "encryption": "Enable Encryption",
+          "allow_raw_commands": "Allow Raw Commands",
           "name": "Name"
         },
         "data_description": {
           "host": "IP address of your Novastar processor",
           "port": "API port (default: 8000)",
           "project_id": "From Settings > OpenAPI Management on your device",
           "secret_key": "From Settings > OpenAPI Management on your device",
-          "encryption": "Enable encrypted communication with the device"
+          "encryption": "Enable encrypted communication with the device",
+          "allow_raw_commands": "Enable sending raw API commands via service call"
         }
       },
       "scan": {
@@ -36,14 +38,16 @@
           "project_id": "Project ID",
           "secret_key": "Secret Key",
           "encryption": "Enable Encryption",
+          "allow_raw_commands": "Allow Raw Commands",
           "name": "Name"
         },
         "data_description": {
           "host": "IP address of your Novastar processor",
           "port": "API port (default: 8000)",
           "project_id": "From Settings > OpenAPI Management on your device",
           "secret_key": "From Settings > OpenAPI Management on your device",
-          "encryption": "Enable encrypted communication with the device"
+          "encryption": "Enable encrypted communication with the device",
+          "allow_raw_commands": "Enable sending raw API commands via service call"
         }
       },
       "credentials": {
@@ -115,5 +119,25 @@
         "name": "Signal Power Status"
       }
     }
+  },
+  "services": {
+    "send_raw_command": {
+      "name": "Send Raw Command",
+      "description": "Send a raw API command to the Novastar processor (requires 'Allow Raw Commands' option).",
+      "fields": {
+        "host": {
+          "name": "Host",
+          "description": "The IP address of the Novastar processor."
+        },
+        "endpoint": {
+          "name": "Endpoint",
+          "description": "The API endpoint path (e.g., 'device/readDetail')."
+        },
+        "body": {
+          "name": "Body",
+          "description": "The JSON body to send with the request."
+        }
+      }
+    }
   }
 }