Home Assistant & Smart Infrastructure Setup (9): Somfy Overkiz Security and Entryway Tracking

Goal: Integrate Somfy TaHoma or Connexoon bridges via the Overkiz platform to monitor entryway doors/windows and programmatically control smart blinds/covers.

Why CLI Scripts? (Agentic AI Observability)

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. Configure Overkiz Platform

1. In Home Assistant UI, navigate to Settings -> Devices & Services -> Add Integration.
2. Select Overkiz (Somfy).
3. Choose your hub provider (e.g. Somfy Europe / TaHoma).
4. Enter your Somfy user credentials.

2. Identifying Blinds & Entryway Sensors

The setup integrates blinds (Somfy cover entities) and entryway tags (Netatmo Smart Security Tags reporting to the Welcome camera, exposed as door/window binary_sensor objects):

• Main blinds: cover.living
• Office blinds: cover.birou
• Bedroom blinds: cover.dormitor_mare
• Kitchen blinds: cover.bucatarie
• Front Door sensor: binary_sensor.front_door_door
• Sandra’s Bedroom Window: binary_sensor.sandra_window_window

3. Programmatic Blind Control Script

3. Programmatic Blind Control Script

To query security tag states, we use the get_ha_sensor.sh CLI utility (detailed in Post 1). To perform actions (such as opening or closing the blinds), create the following control script: /home/gvoina/scripts/control_ha_cover.sh:

#!/usr/bin/env bash
# =============================================================================
# Home Assistant Cover Control Utility
# Allows programmatic control of Somfy blinds/covers
# =============================================================================
set -eo pipefail

ENTITY_ID=$1
ACTION=$2 # open, close, stop, or a position percentage (0-100)

if [[ -z "$ENTITY_ID" || -z "$ACTION" ]]; then
  echo "Usage: $0 <entity_id> <open|close|stop|position_value>"
  exit 1
fi

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

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

if [[ "$ACTION" == "open" ]]; then
  SERVICE="open_cover"
  PAYLOAD="{\"entity_id\": \"$ENTITY_ID\"}"
elif [[ "$ACTION" == "close" ]]; then
  SERVICE="close_cover"
  PAYLOAD="{\"entity_id\": \"$ENTITY_ID\"}"
elif [[ "$ACTION" == "stop" ]]; then
  SERVICE="stop_cover"
  PAYLOAD="{\"entity_id\": \"$ENTITY_ID\"}"
elif [[ "$ACTION" =~ ^[0-9]+$ ]]; then
  SERVICE="set_cover_position"
  PAYLOAD="{\"entity_id\": \"$ENTITY_ID\", \"position\": $ACTION}"
else
  echo "Error: Invalid action. Choose open, close, stop, or an integer position."
  exit 1
fi

RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" \
  "http://localhost:8123/api/services/cover/$SERVICE")

echo "Command sent successfully. API Response: $RESPONSE"

Make the script executable:

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

4. Real-world Command Examples

With the script ready, you (and automated AI agents like agy) can control your covers directly from the terminal:

# 1. Close the living room blinds completely
$ /home/gvoina/scripts/control_ha_cover.sh cover.living close

# 2. Open the office blinds completely
$ /home/gvoina/scripts/control_ha_cover.sh cover.birou open

# 3. Set the master bedroom blinds to 50% open
$ /home/gvoina/scripts/control_ha_cover.sh cover.dormitor_mare 50

# 4. Check if the front door is currently closed
$ /home/gvoina/scripts/get_ha_sensor.sh binary_sensor.front_door_door
Front Door Door: off (off = Closed, on = Open)