get_battery_levels

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:762-785 (handler)

  The main handler function for the 'get_battery_levels' tool. Fetches all devices, filters by battery level (ignoring 255 which means mains/no battery), and returns devices at or below the threshold, sorted ascending.

  @mcp.tool()
  async def get_battery_levels(threshold: int = 20) -> str:
      """Get a list of devices with battery levels at or below the specified threshold.
      
      Args:
          threshold: Battery percentage threshold (default: 20).
      """
      async with create_client() as client:
          devices = await _get_cached_data(client, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")
          results = []
          for dev in devices:
              battery = dev.get("BatteryLevel", 255)
              # BatteryLevel 255 often means no battery or not reporting
              if battery != 255 and battery <= threshold:
                  results.append({
                      "idx": dev.get("idx"),
                      "Name": dev.get("Name"),
                      "BatteryLevel": battery,
                      "HardwareName": dev.get("HardwareName"),
                      "LastUpdate": dev.get("LastUpdate")
                  })
          # Sort by battery level ascending
          results.sort(key=lambda x: x["BatteryLevel"])
          return json.dumps({"status": "OK", "result": results})

• src/domoticz_mcp/server.py:762-785 (registration)

  The tool is registered via the @mcp.tool() decorator on the get_battery_levels function, using the FastMCP instance created at line 70.

  @mcp.tool()
  async def get_battery_levels(threshold: int = 20) -> str:
      """Get a list of devices with battery levels at or below the specified threshold.
      
      Args:
          threshold: Battery percentage threshold (default: 20).
      """
      async with create_client() as client:
          devices = await _get_cached_data(client, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")
          results = []
          for dev in devices:
              battery = dev.get("BatteryLevel", 255)
              # BatteryLevel 255 often means no battery or not reporting
              if battery != 255 and battery <= threshold:
                  results.append({
                      "idx": dev.get("idx"),
                      "Name": dev.get("Name"),
                      "BatteryLevel": battery,
                      "HardwareName": dev.get("HardwareName"),
                      "LastUpdate": dev.get("LastUpdate")
                  })
          # Sort by battery level ascending
          results.sort(key=lambda x: x["BatteryLevel"])
          return json.dumps({"status": "OK", "result": results})

• src/domoticz_mcp/server.py:762-785 (schema)

  The schema/type definition is the function signature: threshold is an int with default 20. Returns a JSON string with status and result array.

  @mcp.tool()
  async def get_battery_levels(threshold: int = 20) -> str:
      """Get a list of devices with battery levels at or below the specified threshold.
      
      Args:
          threshold: Battery percentage threshold (default: 20).
      """
      async with create_client() as client:
          devices = await _get_cached_data(client, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")
          results = []
          for dev in devices:
              battery = dev.get("BatteryLevel", 255)
              # BatteryLevel 255 often means no battery or not reporting
              if battery != 255 and battery <= threshold:
                  results.append({
                      "idx": dev.get("idx"),
                      "Name": dev.get("Name"),
                      "BatteryLevel": battery,
                      "HardwareName": dev.get("HardwareName"),
                      "LastUpdate": dev.get("LastUpdate")
                  })
          # Sort by battery level ascending
          results.sort(key=lambda x: x["BatteryLevel"])
          return json.dumps({"status": "OK", "result": results})

• src/domoticz_mcp/server.py:346-355 (helper)

  The _get_cached_data helper is used internally to fetch and cache device data from the Domoticz API.

  async def _get_cached_data(client: "httpx.AsyncClient", cache_obj: Dict[str, Any], api_url: str, key_path: str = "result") -> List[Dict[str, Any]]:
      now = time.time()
      if cache_obj["data"] is None or (now - cache_obj["timestamp"]) > CACHE_TTL:
          response = await _do_request(client, "GET", api_url)
          cache_obj["data"] = response.json().get(key_path, [])
          cache_obj["timestamp"] = now
      return cache_obj["data"]
  
  async def _resolve_idx(
      client: "httpx.AsyncClient",

• src/domoticz_mcp/server.py:1293-1298 (helper)

  The audit_batteries prompt references get_battery_levels to guide the AI agent in battery auditing.

  @mcp.prompt()
  def audit_batteries(threshold: int = 20) -> str:
      """Prompt to audit battery levels across all sensors."""
      return f"Please check the battery levels of all my smart home devices. Use the `get_battery_levels` tool with a threshold of {threshold}% to identify any sensors that need attention soon. Provide a clear list of these devices, including their current battery percentage and which room they are in (if known)."
  
  @mcp.prompt()