Integrazione API Ajax: Connessione di Ajax a KNX, Home Assistant e sistemi di terze parti

Integrazione Ajax in Home Assistant — configurazione

Prerequisites:
  - Ajax account with hub registered
  - Partner API token (from Ajax PRO Desktop → API Keys)
  - Home Assistant 2024.1+ with HACS installed

Installation:
  1. HACS → Integrations → Search "Ajax Security"
  2. Install integration, restart HA
  3. Settings → Integrations → Add Integration → Ajax Security
  4. Enter API token and select hub(s)

Entities created per hub:
  alarm_control_panel.ajax_hub_[id]   — arm/disarm/night mode
  binary_sensor.[device_name]_motion  — PIR detectors
  binary_sensor.[device_name]_door    — door/window contacts
  binary_sensor.[device_name]_glass   — glass break detectors
  binary_sensor.[device_name]_tamper  — tamper on all devices
  sensor.[device_name]_battery        — battery level (%)
  sensor.[device_name]_signal         — signal strength (%)

Polling interval: 30 seconds (HA polls Ajax Cloud)
Alarm events via webhook: real-time push (see below)

configuration.yaml — movimento Ajax → telegramma KNX

# Home Assistant configuration.yaml (KNX integration)
knx:
  tunnel:
    host: 192.168.1.10  # KNX IP Interface address
    port: 3671

# automations.yaml — Ajax motion detector → KNX
automation:
  - alias: "Ajax MotionCam hallway → KNX lights"
    trigger:
      platform: state
      entity_id: binary_sensor.ajax_motioncam_hallway_motion
      to: "on"
    action:
      service: knx.send
      data:
        address: "3/0/5"     # KNX hallway lights GA
        payload: true
        type: "1byte"

  - alias: "Ajax MotionCam hallway OFF → KNX lights off"
    trigger:
      platform: state
      entity_id: binary_sensor.ajax_motioncam_hallway_motion
      to: "off"
      for: "00:02:00"        # 2-minute hold-off
    action:
      service: knx.send
      data:
        address: "3/0/5"
        payload: false
        type: "1byte"

  - alias: "Ajax alarm → KNX general alarm"
    trigger:
      platform: state
      entity_id: alarm_control_panel.ajax_hub_main
      to: "triggered"
    action:
      service: knx.send
      data:
        address: "8/0/1"     # KNX general alarm GA
        payload: true
        type: "1byte"

Scena KNX "Sto uscendo" → inserimento Ajax

# KNX "I'm leaving" button press (GA 1/0/10 = true)
# triggers HA automation → arms Ajax

automation:
  - alias: "KNX leaving scene → Ajax arm away"
    trigger:
      platform: event
      event_type: knx_event
      event_data:
        address: "1/0/10"    # KNX leaving button GA
        value: true
    action:
      - service: knx.send
        data:
          address: "3/0/0"   # Lights off (all zones)
          payload: false
          type: "1byte"
      - service: knx.send
        data:
          address: "4/0/0"   # HVAC setback mode
          payload: false
          type: "1byte"
      - delay: "00:00:30"    # 30-second exit delay
      - service: alarm_control_panel.alarm_arm_away
        target:
          entity_id: alarm_control_panel.ajax_hub_main
        data:
          code: "1234"       # Master code

  - alias: "Ajax armed → KNX confirmation"
    trigger:
      platform: state
      entity_id: alarm_control_panel.ajax_hub_main
      to: "armed_away"
    action:
      service: knx.send
      data:
        address: "1/0/11"   # KNX armed indicator LED
        payload: true
        type: "1byte"

Payload JSON webhook Ajax — evento allarme

// Ajax webhook POST body (alarm event)
{
  "hubId": "HUB-XXXXXXXX",
  "eventType": "ALARM",
  "deviceId": "DEV-12345678",
  "deviceName": "MotionCam Hallway",
  "deviceType": "MotionCam",
  "zoneId": 3,
  "zoneName": "Ground Floor",
  "timestamp": "2025-04-15T14:32:10Z",
  "alarmReason": "MOTION_DETECTED"
}

// Event types:
//   ALARM          — motion, door open, glass break
//   TAMPER         — device opened or removed
//   ARM            — system or group armed
//   DISARM         — system or group disarmed
//   POWER_LOSS     — hub external power lost
//   BATTERY_LOW    — device battery below 10%
//   SIGNAL_LOSS    — device communication lost

// Test webhook (curl):
curl -X POST https://your-ha-instance.duckdns.org/api/webhook/ajax_test \
  -H "Content-Type: application/json" \
  -d '{"eventType":"ALARM","deviceName":"Test","alarmReason":"TEST"}'