Kami Package Detection

SKILL.md

---
name: kami-package-detection
description: A free skill by Kami SmartHome. Get notified the moment a package arrives at your door. Detects packages, parcels, and bags from RTSP camera streams using AI vision.
version: 1.0.4
author: kami-smarthome
tags:
  - smart-home
  - kami
  - home-assistant
  - smarthome
  - detect
  - object-detection
  - yolo
  - package-detection
  - parcel-detection
  - iot
  - camera
  - rtsp
  - onnx
  - edge-ai
  - delivery
  - monitoring
  - notification
triggers:
  - smart home
  - kami
  - home assistant
  - detect
  - detect packages
  - detect parcels
  - kami package
  - kami smart home
  - home assistant package
  - smart home delivery
  - check doorstep
  - delivery notification
  - check for deliveries
  - package detection
  - is there a package
  - monitor packages
  - check camera for packages
  - any deliveries at the door
  - parcel alert
metadata:
  openclaw:
    requires:
      bins:
        - python3.10
      hardware:
        cpu: "2+ cores (x86_64 / ARM64)"
        memory: "2 GB+"
        storage: "2 GB+"
        gpu: "optional (speeds up ONNX inference)"
      network:
        - "RTSP camera access (LAN)"
        - "Internet (KamiClaw API)"
      devices:
        - "RTSP IP camera"
    emoji: "📦"
---

# Kami Package Detection

> Get notified the moment a package arrives at your door.

Monitor your camera feed for packages, parcels, backpacks, handbags, and suitcases. When detected, returns the object class and bounding box as JSON — ready for automation.

### Features

- 📦 Package & parcel detection
- 🧳 Suitcase / backpack / handbag recognition
- 🏠 Doorstep & reception monitoring
- ⏱ Configurable detection duration
- 🔔 JSON output for easy integration

### Scenarios

- Doorstep delivery waiting
- Office reception package management
- Warehouse cargo monitoring
- Temporary item watch

## Installation

```bash
bash setup.sh
```

Creates `.venv/` and installs `onnxruntime`, `opencv-python-headless`, `numpy`. Idempotent.

## Prerequisites

- `python3` and `python3-venv` installed
- `yolov8s-worldv2.onnx` model file in the skill directory
- RTSP camera online and reachable

### Model

The `yolov8s-worldv2.onnx` model file is included in the skill package. If missing, re-download this skill from ClawHub:

```bash
clawhub install kami-package-detection
```

Alternatively, download the YOLOv8s-World v2 `.pt` model from [Ultralytics YOLO-World](https://docs.ultralytics.com/models/yolo-world/) and export it to ONNX yourself. Make sure the class names used during export match the `--class_names` parameter:

```bash
pip install ultralytics
yolo export model=yolov8s-worldv2.pt format=onnx imgsz=320
cp yolov8s-worldv2.onnx /path/to/kami-package-detection/
```

## Parameter Confirmation

Parameters can be supplied via either `config.json` (recommended for repeated use) or command-line flags. Command-line flags override `config.json`, which overrides built-in defaults.

| Parameter | `config.json` field | Default | Description |
|-----------|---------------------|---------|-------------|
| `--rtsp_url` | `rtsp_url` | `rtsp://127.0.0.1/live/TNPUSAQ-757597-DRFMY` | RTSP camera URL |
| `--conf_threshold` | `conf_threshold` | `0.25` | Confidence threshold (0.0–1.0) |
| `--class_names` | *(not in config.json)* | `parcel package "delivery box" person "Cardboard box" "Packaging Box" backpack handbag suitcase` | Classes to detect (CLI only) |
| `--run_time` | `run_time` | `60` | Max seconds; `0` = unlimited |

> When installed as part of `kami-smarthome-suite`, `rtsp_url`, `conf_threshold` and `run_time` are auto-distributed into `config.json` from the central `kami_config.json`. `class_names` is intentionally NOT distributed and stays a per-skill default.

**Ask the user: do any parameters need to be changed?**

## Usage

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

# Or override via CLI
.venv/bin/python yolo_world_onnx.py \
  --rtsp_url rtsp://your-camera-address \
  --run_time 60
```

## Output (stdout JSON)

```json
{
  "detections": [
    {
      "class_name": "parcel",
      "bbox": {"x1": 100, "y1": 200, "x2": 300, "y2": 400}
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `class_name` | string | Detected object class |
| `bbox.x1, y1, x2, y2` | int | Bounding box coordinates |

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Target detected, JSON output written |
| `1` | Error (model missing, RTSP failure, runtime exception) |
| `2` | Timeout, no target detected within `--run_time` |

## Troubleshooting

- `bash: .venv/bin/python: No such file or directory` → Run `bash setup.sh`
- `Model file not found` → Place `yolov8s-worldv2.onnx` in the skill directory
- `Cannot open video` → Check camera is online and `--rtsp_url` is correct

## Privacy Notice

This skill processes camera video stream frames for object detection. Please review the following privacy information before use:

### Pure Local Inference

- Detection runs entirely on-device via the YOLOv8-World ONNX model — **no API key, no cloud calls, no external network traffic**
- The only outbound traffic is the RTSP pull from your own camera (LAN)

### Local Data Storage

- Frames are held in memory only and discarded after each inference — **nothing is persisted to disk**
- The skill emits a single JSON object to **stdout**; if you need history, the caller is responsible for storing it

### User Control

- Camera URL is supplied by the user; this skill will not auto-discover or connect to cameras
- You can stop the skill at any time — there is no background daemon, no cache, and no residual data
- Removing the skill directory wipes everything (model file + venv); nothing else is touched on the host

> For more details on our privacy policy, visit: https://kamiclaw-skill.kamihome.com/privacy