shield_lock
JinDaGe
← Back to skills
extension
Category: OtherAPI key required

Kami Fall Detection

Detect fall events from RTSP camera streams using KamiClaw cloud API. No local GPU needed.

personAuthor: 13681882136hubclawhub
open_in_newRepositorydownloadDownload package

Kami Fall Detection (Cloud)

Detect fall events from RTSP camera streams using the KamiClaw cloud API. No local GPU needed — all inference runs server-side.

🚀 Quick Start

  1. Get API key → https://kamiclaw-skill.kamihome.com (200 free credits for new users)
  2. Tell the agent: Your API key + RTSP camera URL
  3. Choose notifications: Feishu / Telegram / Discord (any combination)
  4. Agent configures everything automatically
  5. Run! → Monitors 24/7, alerts instantly on fall detection

What It Does

  • 🎥 Monitors RTSP camera streams continuously
  • 🧠 Uses cloud AI to detect fall events (active falling, fallen posture, etc.)
  • 📱 Sends instant notifications via Feishu, Telegram, or Discord
  • 💾 Saves alarm video clips for review (optional)
  • 🔄 Auto-reconnects if stream drops

🔒 Privacy & Data Policy

In short: Only 8-second alarm clips are sent to the cloud for AI analysis. No continuous streaming, no audio, no full video.

| What | Local | Cloud | |------|-------|-------| | Video stream / file | ✅ Processed locally | ❌ Never sent | | 8-second alarm clips | ✅ Saved (optional) | ✅ Sent for AI analysis | | Audio | ❌ Not collected | ❌ Not collected |

📄 Full details: Read our Privacy Policy for complete information on data handling, retention, and your rights.

Quick Tips

  • Disable local storage: Set save_alarm_clips: false to not save clips locally
  • Clean up old files: find logs/clips/ -type f -mtime +30 -delete
  • Protect your API key: Never commit config.json to git

ℹ️ AI analysis requires sending alarm clips to the cloud API. Processed clips are retained per the provider's data retention policy.

Configuration

All settings are in config.json. The agent auto-fills this when you provide values in chat.

Essential Settings

| Field | Default | Description | |-------|---------|-------------| | api_key | "" | Required. KamiClaw API key | | cameras | [] | Required. Array of {name, rtsp_url} entries. Single entry: name optional, defaults to "default". Two or more entries: every entry must have a unique non-empty name. | | save_alarm_clips | true | Save alarm video clips to logs/clips/ | | feishu_webhook_url | "" | Feishu webhook URL for alarm notifications | | telegram_bot_token | "" | Telegram bot token for alarm notifications | | telegram_chat_id | "" | Telegram chat ID (user or group) | | discord_webhook_url | "" | Discord webhook URL (push notifications) | | discord_bot_token | "" | Discord bot token (two-way capable) | | discord_channel_id | "" | Discord channel ID (for bot) |

Camera Setup

All cameras are declared in the cameras array. Each entry has just two fields: name and rtsp_url.

Single camera (one entry). name is optional — if omitted it defaults to "default":

{
  "cameras": [
    { "rtsp_url": "rtsp://192.168.1.100/live/stream" }
  ]
}

Multiple cameras (two or more entries). Every entry must have a unique, non-empty name. Strongly recommended: pick a meaningful location label so the operator immediately knows which camera triggered.

{
  "cameras": [
    { "name": "front_door", "rtsp_url": "rtsp://192.168.1.101/live/stream" },
    { "name": "backyard",   "rtsp_url": "rtsp://192.168.1.102/live/stream" }
  ]
}
  • name is shown in every Feishu / Telegram / Discord push and tags every log line.
  • One worker thread per camera; a single stream loss does not affect the others.
  • The skill refuses to start if cameras is empty, or if multiple entries are missing/sharing a name.

Common Brand RTSP Templates

MUST show this table to the user when configuring cameras, so they can pick a URL pattern based on their brand:

| Brand key | Brand | URL pattern | |-----------|-------|-------------| | hikvision | Hikvision | rtsp://{user}:{pwd}@{ip}:554/Streaming/Channels/101 (101=ch1 main, 102=ch1 sub) | | dahua | Dahua | rtsp://{user}:{pwd}@{ip}:554/cam/realmonitor?channel=1&subtype=0 (subtype=0 main, 1 sub) | | tplink | TP-Link | rtsp://{user}:{pwd}@{ip}:554/stream1 (stream1 main, stream2 sub) | | ezviz | EZVIZ | rtsp://admin:{verify_code}@{ip}:554/H264/ch1/main/av_stream | | uniview | Uniview | rtsp://{user}:{pwd}@{ip}:554/media/video1 | | reolink | Reolink | rtsp://{user}:{pwd}@{ip}:554/h264Preview_01_main |

Advanced Settings

| Field | Default | Description | |-------|---------|-------------| | run_time | 0 | Max run time in seconds; 0 = unlimited | | pre_seconds | 3.0 | Seconds buffered before motion trigger | | post_seconds | 3.0 | Seconds collected after motion trigger |

Notification Setup

Tell the agent which channels you want. They'll guide you through setup.

Quick Guide

| Channel | Push Only | Two-Way Capable | |---------|-----------|----------------| | Feishu | Webhook URL | Group Bot (same config) | | Telegram | Bot Token + Chat ID | + Gateway Service | | Discord | Webhook URL | Bot Token + Channel ID |

💡 Discord: Bot token + channel ID gives you full two-way capability. Webhook is simpler for push-only.

💡 Need help? Ask OpenClaw for guidance.

Running

# With config.json (recommended)
.venv/bin/python fall_detect_cloud_skill.py

# Or override the API key on the CLI
.venv/bin/python fall_detect_cloud_skill.py \
    --api_key sk_live_xxxxxxxx

Cameras are always declared in config.json under the cameras array — there is no CLI flag for the RTSP URL.

The skill runs continuously. It does NOT stop after an alarm — it resets and keeps monitoring.

Output Format

Fall detected:

{
  "alarm": true,
  "type": "fall",
  "camera_name": "front_door",
  "fall_type": "active_falling",
  "num_persons": 1,
  "confidence": 0.92,
  "reason": "Person collapsed from standing to floor near bed",
  "frame": 87,
  "source": "rtsp://192.168.1.101/live/stream",
  "clip": "logs/clips/alarm_fall_20260429_143201.mp4"
}

Normal exit (run time reached):

{
  "alarm": false,
  "type": null,
  "detail": "Run time limit reached, no fall detected",
  "frames_processed": 3600,
  "source": "rtsp://192.168.1.100/live/stream"
}

Exit Codes

| Code | Meaning | |------|---------| | 0 | Normal exit (run time reached) | | 1 | Error (invalid API key, missing config, etc.) |

Advanced: How It Works

<details> <summary>Click to expand technical details</summary>

Stage 1 — Change Detection (Local, CPU-only)

  • Lightweight frame-differencing on 128×128 grayscale
  • Maintains rolling pre-buffer (default 4s)
  • Triggers Stage 2 on significant temporal change

Stage 2 — Cloud Analysis

  • Collects post-transition frames (default 4s)
  • Resizes clip to 360×360, writes to temp file
  • Sends to KamiClaw API (detectType: FALL, detectSubType: SK_FALL_DETECTION)
  • On fall detected: outputs JSON alarm, optionally saves clip, resets to Stage 1

Auto-Reconnect

  • If RTSP stream drops, retries connection every 5 seconds
  • Resumes monitoring seamlessly after reconnection
</details>

Agent Setup Flow

For agents configuring this skill:

  1. Read config.json — check whether api_key is set and whether cameras is a non-empty array.
  2. If api_key is empty, ask the user: "Please provide your KamiClaw API key. Register at https://kamiclaw-skill.kamihome.com".
  3. If cameras is empty, ask: "How many RTSP cameras do you want to monitor?"
    • One camera: ask only for the RTSP URL. Write [ { "rtsp_url": "..." } ] — name will default to "default" automatically.
    • Two or more cameras: for each one, ask both the RTSP URL and a unique short location label (e.g. front_door, backyard, living_room). Strongly recommend the user picks meaningful labels — they are shown in every alarm notification. Write [ { "name": "front_door", "rtsp_url": "..." }, { "name": "backyard", "rtsp_url": "..." } ].
  4. Ask: "Save alarm video clips? (yes/no, default: yes)" → set save_alarm_clips.
  5. Ask about each notification channel (Feishu / Telegram / Discord) — guide setup if yes.
  6. Write all values to config.json (read existing, merge, write back).
  7. Optionally run python fall_detect_cloud_skill.py --list_cameras to confirm the resolved camera list.
  8. Run the skill.

Never run with an empty api_key. Never run with cameras empty. When the user has multiple cameras, never accept missing/duplicate names — re-prompt until each camera has a unique label. Never ask the user to manually edit config.json.

Troubleshooting & Analysis

Log Files

| File | Content | |------|---------| | logs/app.log | Application log (rotates daily, keeps 30 days) | | logs/alarms.jsonl | All alarm events + clip analysis results | | logs/transitions.jsonl | All motion trigger events |

Quick Analysis Commands

# Count alarms today
grep '"alarm"' logs/alarms.jsonl | grep "$(date +%Y-%m-%d)" | wc -l

# Transitions vs alarms (false positive rate)
wc -l logs/transitions.jsonl logs/alarms.jsonl

# Export alarms as CSV
cat logs/alarms.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    obj = json.loads(line)
    if obj.get('event') == 'alarm':
        print(f\"{obj['_ts']},{obj.get('type','')},{obj.get('fall_type','')},{obj.get('confidence',0)},{obj.get('frame',0)}\")
"

Common Issues

| Issue | Solution | |-------|----------| | No alarms detected | Check RTSP stream is active; verify camera angle covers monitoring area | | Too many false alarms | Adjust camera position; reduce motion sensitivity area | | API errors | Verify API key is valid; check internet connection | | Stream disconnects | Check network stability; camera may need reboot |

File Structure

kami-fall-detection/
├── SKILL.md                      # Documentation
├── config.json                   # Configuration (auto-managed by agent)
├── fall_detect_cloud_skill.py    # Production entry point
├── setup.sh                      # Installer
└── requirements.txt              # Dependencies