path: root/Biz/Kidcam/README.md

# Kidcam - Motion-Activated Family Video Streaming

Kidcam is an intelligent video monitoring system that detects people, sends Telegram notifications, and provides RTSP streaming. Designed for Jetson Nano and similar ARM-based systems.

## Quick Start

```bash
# Clone repository
git clone git@simatime.com:omni.git
cd omni

# Deploy (on Jetson Nano running Ubuntu 20.04)
sudo Biz/Kidcam/deploy.sh

# Configure Telegram credentials
sudo nano /etc/kidcam/config.env

# Start service
sudo systemctl start kidcam

# Check status
sudo systemctl status kidcam
sudo journalctl -u kidcam -f
```

## Hardware Requirements

### Minimum
- **Device**: NVIDIA Jetson Nano (4GB recommended)
- **OS**: Ubuntu 20.04 LTS (ARM64)
- **Camera**: USB webcam or CSI camera module
- **Storage**: 16GB+ microSD card
- **Network**: WiFi or Ethernet connection

### Recommended
- 32GB+ microSD card for logging and model caching
- 5V 4A power supply for Jetson Nano
- Camera with 1080p resolution

## Installation

### Automated Deployment

The deployment script handles everything:

```bash
sudo Biz/Kidcam/deploy.sh
```

This script:
1. Verifies system is Ubuntu 20.04 on aarch64
2. Creates `kidcam` system user
3. Installs system dependencies (Python, OpenCV, GStreamer)
4. Sets up Python virtual environment at `/opt/kidcam/venv`
5. Installs Python packages (ultralytics, telegram bot, opencv)
6. Creates directories: `/opt/kidcam` and `/etc/kidcam`
7. Installs and enables systemd service
8. Creates example configuration file

### Manual Installation

If you prefer manual setup:

```bash
# 1. Install system dependencies
sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-opencv \
    gstreamer1.0-tools v4l-utils

# 2. Create user and directories
sudo useradd --system --no-create-home kidcam
sudo usermod -aG video kidcam
sudo mkdir -p /opt/kidcam /etc/kidcam

# 3. Copy project files
sudo rsync -av ./ /opt/kidcam/

# 4. Setup Python environment
sudo python3 -m venv /opt/kidcam/venv
sudo /opt/kidcam/venv/bin/pip install ultralytics python-telegram-bot opencv-python

# 5. Install systemd service
sudo cp Biz/Kidcam/kidcam.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable kidcam
```

## Configuration

Edit `/etc/kidcam/config.env`:

```bash
# Camera Configuration
CAMERA_DEVICE=/dev/video0        # USB camera (use /dev/video1 for CSI)
STREAM_PORT=8554                 # RTSP streaming port

# Detection Parameters
DETECTION_CONFIDENCE=0.5         # Confidence threshold (0.0-1.0)
COOLDOWN_MINUTES=5               # Minutes before re-triggering

# Telegram Bot Setup
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=123456789

# Python Path
PYTHONPATH=/opt/kidcam
```

### Getting Telegram Credentials

1. **Create Bot**:
   - Message [@BotFather](https://t.me/BotFather) on Telegram
   - Send `/newbot` and follow instructions
   - Copy the bot token

2. **Get Chat ID**:
   - Start a chat with your new bot
   - Send any message
   - Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
   - Find `"chat":{"id":123456789}` in the JSON response

### Camera Device Selection

```bash
# List available cameras
v4l2-ctl --list-devices

# Test camera
ffmpeg -f v4l2 -i /dev/video0 -frames 1 test.jpg
```

Common devices:
- `/dev/video0` - USB webcam
- `/dev/video1` - CSI camera (Jetson)

## Service Management

```bash
# Start service
sudo systemctl start kidcam

# Stop service
sudo systemctl stop kidcam

# Restart service
sudo systemctl restart kidcam

# View status
sudo systemctl status kidcam

# Enable auto-start on boot
sudo systemctl enable kidcam

# Disable auto-start
sudo systemctl disable kidcam

# View logs (live)
sudo journalctl -u kidcam -f

# View last 100 lines
sudo journalctl -u kidcam -n 100

# View logs since boot
sudo journalctl -u kidcam -b
```

## Testing Individual Modules

### Test Camera Access

```bash
# Check camera permissions
ls -l /dev/video0
groups kidcam  # Should include 'video' group

# Capture test image
v4l2-ctl --device=/dev/video0 --stream-mmap --stream-count=1 \
         --stream-to=test.jpg
```

### Test Person Detection

```bash
cd /opt/kidcam
source venv/bin/activate
python3 -c "
import Biz.Kidcam.Detector as Detector
detector = Detector.PersonDetector('/dev/video0', 0.5)
print('Detector initialized')
"
```

### Test Telegram Notifications

```bash
cd /opt/kidcam
source venv/bin/activate
python3 -c "
import os
import Biz.Kidcam.Notifier as Notifier
notifier = Notifier.TelegramNotifier(
    os.getenv('TELEGRAM_BOT_TOKEN'),
    os.getenv('TELEGRAM_CHAT_ID')
)
import asyncio
asyncio.run(notifier.send_notification('Test message'))
"
```

### Test RTSP Streaming

```bash
cd /opt/kidcam
source venv/bin/activate
python3 -c "
import Biz.Kidcam.Streamer as Streamer
streamer = Streamer.VideoStreamer('/dev/video0', 8554)
print('Streamer initialized')
"
```

View stream with VLC:
```bash
vlc rtsp://localhost:8554/stream
```

## Troubleshooting

### Service Won't Start

```bash
# Check detailed error logs
sudo journalctl -u kidcam -n 50 --no-pager

# Verify configuration
sudo cat /etc/kidcam/config.env

# Test manual start
cd /opt/kidcam
sudo -u kidcam venv/bin/python3 -m Biz.Kidcam.Core
```

### Camera Not Detected

```bash
# List all video devices
v4l2-ctl --list-devices

# Check permissions
ls -l /dev/video*
groups kidcam  # Must include 'video'

# Verify camera works
ffplay /dev/video0
```

### Import Errors

```bash
# Verify PYTHONPATH
grep PYTHONPATH /etc/kidcam/config.env

# Check Python path in virtual environment
cd /opt/kidcam
source venv/bin/activate
python3 -c "import sys; print('\n'.join(sys.path))"

# Reinstall packages
sudo -u kidcam venv/bin/pip install --upgrade ultralytics python-telegram-bot
```

### Telegram Not Working

```bash
# Test bot token
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# Check network connectivity
ping api.telegram.org

# Verify environment variables are loaded
sudo systemctl show kidcam -p Environment
```

### High CPU/Memory Usage

```bash
# Check resource usage
top -u kidcam

# Increase cooldown period
sudo nano /etc/kidcam/config.env
# Set COOLDOWN_MINUTES=10 or higher

# Lower detection confidence
# Set DETECTION_CONFIDENCE=0.7  (fewer detections)
```

### RTSP Stream Issues

```bash
# Check if port is open
sudo netstat -tulpn | grep 8554

# Test with ffplay
ffplay rtsp://localhost:8554/stream

# Check GStreamer plugins
gst-inspect-1.0 | grep rtsp
```

## Architecture

### State Machine

Kidcam operates in three states:

1. **IDLE**: Monitoring for person detection
2. **ACTIVE**: Person detected, streaming and sending notifications
3. **COOLDOWN**: Waiting before re-triggering

### Components

- **Core.py**: Main orchestration service
- **Detector.py**: YOLO-based person detection
- **Streamer.py**: GStreamer RTSP video streaming
- **Notifier.py**: Telegram bot integration

### Data Flow

```
Camera → Detector → [Person?] → Core → Streamer + Notifier
                                   ↓
                              State Machine
```

## Performance Tuning

### Jetson Nano Optimization

```bash
# Max performance mode
sudo nvpmodel -m 0
sudo jetson_clocks

# Check power mode
sudo nvpmodel -q
```

### Reduce Resource Usage

Edit `/etc/kidcam/config.env`:
```bash
# Lower resolution in Streamer.py configuration
# Increase detection interval
COOLDOWN_MINUTES=15

# Higher confidence = fewer false positives
DETECTION_CONFIDENCE=0.7
```

## Development

### Local Testing (Non-Jetson)

```bash
# Build with bild
bild Biz/Kidcam/Core.py

# Run directly
python3 -m Biz.Kidcam.Core

# Run with custom config
CAMERA_DEVICE=/dev/video0 python3 -m Biz.Kidcam.Core
```

### Linting and Type Checking

```bash
# Lint
lint Biz/Kidcam/*.py

# Type check
typecheck.sh Biz/Kidcam/Core.py
```

## Security Considerations

- Service runs as unprivileged `kidcam` user
- Config file has restricted permissions (640)
- Network access limited to Telegram API and RTSP
- systemd hardening applied (NoNewPrivileges, ProtectSystem, etc.)

## License

See repository root for license information.

## Support

For issues or questions:
1. Check logs: `sudo journalctl -u kidcam -f`
2. Review this troubleshooting guide
3. File issue in repository