1 files changed, 403 insertions, 0 deletions
diff --git a/Biz/Kidcam/README.md b/Biz/Kidcam/README.md
new file mode 100644
index 0000000..fa69c3c
--- /dev/null
+++ b/Biz/Kidcam/README.md
@@ -0,0 +1,403 @@
+# 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