---
name: kami-fall-detection-cloud
description: Detect fall events from RTSP camera streams using KamiClaw cloud API. No local GPU needed.
version: 1.0.7
author: kami-smarthome
tags:
 - smart-home
 - fall-detection
 - elderly-care
 - cloud-ai
 - rtsp
 - camera
triggers:
 - detect fall
 - fall detection cloud
 - check for falls
 - monitor elderly
 - cloud fall detection
 - home assistant
 - smart home
metadata:
 openclaw:
  requires:
   bins:
   - python3
   - ffmpeg
   env:
   - KAMICLAW_API_KEY
  primaryEnv: KAMICLAW_API_KEY
  emoji: "🚨"
  hardware:
   cpu: "4+ cores (x86_64 / ARM64)"
   memory: "8 GB+"
   storage: "20 GB+"
   gpu: "optional (speed up ONNX inference)"
   network:
   - "RTSP camera access (LAN)"
   - "Internet (KamiClaw API)"
   devices:
   - "RTSP IP camera"
---

# 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](https://kamiclaw-skill.kamihome.com/privacy) 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 |
| `rtsp_url` | `""` | **Required.** RTSP stream URL or local video file path |
| `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) |

### 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

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

# Or with CLI arguments
.venv/bin/python fall_detect_cloud_skill.py \
    --rtsp_url rtsp://192.168.1.100/live/stream \
    --api_key sk_live_xxxxxxxx
```

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

---

## Output Format

**Fall detected:**
```json
{
  "alarm": true,
  "type": "fall",
  "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.100/live/stream",
  "clip": "logs/clips/alarm_fall_20260429_143201.mp4"
}
```

**Normal exit (run time reached):**
```json
{
  "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 if `api_key` and `rtsp_url` are non-empty
2. If empty, ask user:
   - API key: "Please provide your KamiClaw API key. Register at https://kamiclaw-skill-api.kamihome.com/v1/detect"
   - RTSP URL: "Please provide your RTSP camera URL (e.g., rtsp://192.168.1.100/live/stream)"
3. Ask: "Save alarm video clips? (yes/no, default: yes)" → set `save_alarm_clips`
4. Ask about each notification channel (Feishu/Telegram/Discord) — guide setup if yes
5. Write all values to `config.json` (read existing, merge, write back)
6. Run the skill

**Never run with empty `api_key` or `rtsp_url`. Never ask 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

```bash
# 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
├── fall_detect_cloud.py          # Development/debug version
├── setup.sh                      # Installer
└── requirements.txt              # Dependencies
```