Home Assistant & Smart Infrastructure Setup (3): EdgeMAX Infrastructure Status Monitoring via UISP Cloud API

Goal: Leverage the UISP API from your EdgeMAX controller to monitor hardware health (CPU load, RAM usage, System Temperatures, and System Uptime) for routers and switches.

Before jumping into the script code, it is important to understand why command-line scripts are extremely useful for modern smart homes. Beyond convenience for terminal users, these CLI scripts act as a programmatic interface (API bridge) for agentic AI assistants like Antigravity (agy).

By exposing Home Assistant states through standard shell scripts, an AI agent running in your workspace can query, check, and verify live IoT metrics or network states autonomously. This enables the agent to check if the network is healthy, read environment levels, or verify configurations without having to scrape web-based dashboards or utilize complex browser interfaces. It bridges human developer terminal workflows with agentic automation.

Step-by-Step Configuration

1. Generate a UISP API Key

1. Access your UISP Controller (e.g., https://voina.uisp.com/).
2. Go to Settings -> Users -> API Tokens.
3. Click “Add token”, name it Hass-Infrastructure and copy the string.
4. Save the token to /home/gvoina/homeassistant/uisp_api_key.txt.

2. Create the System Telemetry Script

Write /home/gvoina/scripts/get_uisp_status.sh:

#!/usr/bin/env bash
set -eo pipefail

KEY_FILE="/home/gvoina/homeassistant/uisp_api_key.txt"
if [[ ! -f "$KEY_FILE" ]]; then
  echo "Error: UISP Cloud API token not found at $KEY_FILE."
  exit 1
fi

API_TOKEN=$(cat "$KEY_FILE" | tr -d '\r\n[:space:]')

# Query the centralized UISP devices endpoint
RESPONSE=$(curl -s -X GET \
  -H "x-auth-token: $API_TOKEN" \
  -H "Accept: application/json" \
  "https://voina.uisp.com/nms/api/v2.1/devices")

if echo "$RESPONSE" | jq -e '.[]' >/dev/null 2>&1; then
  echo "================================================= UISP DEVICE STATUS ================================================="
  printf "%-22s | %-12s | %-15s | %-8s | %-8s | %-8s | %-8s | %-12s\n" "Device Name" "Site" "Model" "Status" "CPU" "RAM" "Temp" "Uptime"
  echo "----------------------------------------------------------------------------------------------------------------------"
  
  echo "$RESPONSE" | jq -c '.[]' | while read -r row; do
    NAME=$(echo "$row" | jq -r '.identification.name // "Unknown"')
    MODEL=$(echo "$row" | jq -r '.identification.modelName // .identification.model // "N/A"')
    SITE=$(echo "$row" | jq -r '.identification.site.name // "N/A"')
    STATUS=$(echo "$row" | jq -r '.overview.status // "offline"')
    
    if [[ "$MODEL" == "Unknown" ]]; then
      continue
    fi

    # Metrics
    CPU=$(echo "$row" | jq -r '.overview.cpu // "0"')
    RAM=$(echo "$row" | jq -r '.overview.ram // "0"')
    TEMP=$(echo "$row" | jq -r '.overview.temperature // "N/A"')
    UPTIME_SEC=$(echo "$row" | jq -r '.overview.uptime // "0"')

    # Format Uptime to Days/Hours
    if [[ "$UPTIME_SEC" -gt 0 && "$UPTIME_SEC" != "null" ]]; then
      DAYS=$((UPTIME_SEC / 86400))
      HOURS=$(((UPTIME_SEC % 86400) / 3600))
      UPTIME="${DAYS}d ${HOURS}h"
    else
      UPTIME="N/A"
    fi

    # Format temperature
    if [[ "$TEMP" =~ ^[0-9.]+$ ]]; then
      TEMP="${TEMP}°C"
    elif [[ "$TEMP" == "null" || -z "$TEMP" ]]; then
      TEMP="N/A"
    fi

    # Format CPU/RAM percentages
    if [[ "$CPU" != "null" && -n "$CPU" ]]; then
      CPU="${CPU}%"
    else
      CPU="N/A"
    fi

    if [[ "$RAM" != "null" && -n "$RAM" ]]; then
      RAM="${RAM}%"
    else
      RAM="N/A"
    fi

    if [[ "$STATUS" == "active" ]]; then
      STATUS="online"
    fi

    printf "%-22s | %-12s | %-15s | %-8s | %-8s | %-8s | %-8s | %-12s\n" "$NAME" "$SITE" "$MODEL" "$STATUS" "$CPU" "$RAM" "$TEMP" "$UPTIME"
  done
  echo "======================================================================================================================"
else
  echo "Error: Failed to query UISP Cloud API."
  exit 1
fi

Make the script executable:

chmod +x /home/gvoina/scripts/get_uisp_status.sh