leetcrypt
9f73595b20
- Expanded protocol database from 18 → 299 signatures (16.6x increase) - Imported 281 protocols from RTL_433 open-source database (286 total devices) - Created automated import script: scripts/import_rtl433_protocols.py - Generated rtl433_protocols_imported.py with timing/frequency/modulation data - Updated protocol_database.py to include RTL433_PROTOCOLS - All 26 tests passing Breakdown by category: - Weather: 116 protocols - Sensors: 36 protocols - TPMS: 25 protocols - Security: 23 protocols - Home Automation: 18 protocols - Other: 50+ protocols Frequency coverage: - 433.92 MHz: 248 protocols - 315.00 MHz: 32 protocols - 915.00 MHz: 1 protocol This provides comprehensive coverage of Sub-GHz IoT devices for accurate identification from raw RF captures.
288 lines
5.8 KiB
Markdown
288 lines
5.8 KiB
Markdown
# GigLez - Quick Start Guide
|
|
|
|
## 🚀 Installation (One Command)
|
|
|
|
```bash
|
|
./scripts/safe_install.sh --create-venv && source venv/bin/activate && ./scripts/safe_install.sh --all
|
|
```
|
|
|
|
That's it! Everything is installed and ready.
|
|
|
|
---
|
|
|
|
## 📦 Safe Package Installation
|
|
|
|
### Why Regular `pip install` Might Not Work
|
|
|
|
Common issues:
|
|
- ❌ No virtual environment (installs system-wide, permission errors)
|
|
- ❌ Old pip version (compatibility issues)
|
|
- ❌ Dependency conflicts (breaks existing packages)
|
|
- ❌ No rollback (can't undo if something breaks)
|
|
|
|
### Solution: Use Our Safe Install Script
|
|
|
|
✅ Auto-creates/activates virtual environment
|
|
✅ Checks for conflicts before installing
|
|
✅ Creates backups automatically
|
|
✅ Can rollback if something goes wrong
|
|
✅ Upgrades pip automatically
|
|
✅ Verifies installation success
|
|
|
|
---
|
|
|
|
## Common Commands
|
|
|
|
### First Time Setup
|
|
|
|
```bash
|
|
# 1. Create virtual environment
|
|
./scripts/safe_install.sh --create-venv
|
|
|
|
# 2. Activate it
|
|
source venv/bin/activate
|
|
|
|
# 3. Install all dependencies
|
|
./scripts/safe_install.sh --all
|
|
```
|
|
|
|
### Daily Use
|
|
|
|
```bash
|
|
# Activate virtual environment (every time you work)
|
|
source venv/bin/activate
|
|
|
|
# Verify environment
|
|
./scripts/safe_install.sh --check
|
|
```
|
|
|
|
### Installing Packages
|
|
|
|
```bash
|
|
# Install single package (safe way)
|
|
./scripts/safe_install.sh package_name
|
|
|
|
# Install specific version
|
|
./scripts/safe_install.sh package_name 2.0.0
|
|
|
|
# Example: Install psycopg2
|
|
./scripts/safe_install.sh psycopg2-binary
|
|
```
|
|
|
|
### Troubleshooting
|
|
|
|
```bash
|
|
# Check what's installed
|
|
pip list
|
|
|
|
# Check for package conflicts
|
|
pip check
|
|
|
|
# Create backup before making changes
|
|
./scripts/safe_install.sh --backup
|
|
|
|
# If something breaks, rollback
|
|
./scripts/safe_install.sh --rollback .pip_backups/installed_packages_YYYYMMDD_HHMMSS.txt
|
|
```
|
|
|
|
---
|
|
|
|
## Why This Works When Regular pip Doesn't
|
|
|
|
### Problem: "pip: command not found"
|
|
|
|
**Regular way (fails):**
|
|
```bash
|
|
pip install something # Error: command not found
|
|
```
|
|
|
|
**Our way (works):**
|
|
```bash
|
|
./scripts/safe_install.sh something
|
|
# Script checks for pip, installs if missing, then installs package
|
|
```
|
|
|
|
### Problem: "Permission denied"
|
|
|
|
**Regular way (fails):**
|
|
```bash
|
|
pip install something # Error: Permission denied
|
|
sudo pip install something # BAD! Installs system-wide
|
|
```
|
|
|
|
**Our way (works):**
|
|
```bash
|
|
./scripts/safe_install.sh something
|
|
# Script creates/uses virtual environment, no sudo needed
|
|
```
|
|
|
|
### Problem: "Dependency conflict"
|
|
|
|
**Regular way (fails):**
|
|
```bash
|
|
pip install something # Breaks existing packages silently
|
|
```
|
|
|
|
**Our way (works):**
|
|
```bash
|
|
./scripts/safe_install.sh something
|
|
# Script checks for conflicts, backs up, asks confirmation
|
|
```
|
|
|
|
---
|
|
|
|
## Manual Alternative (If Script Doesn't Work)
|
|
|
|
### Step-by-Step
|
|
|
|
```bash
|
|
# 1. Check Python version (must be 3.9+)
|
|
python3 --version
|
|
|
|
# 2. Create virtual environment manually
|
|
python3 -m venv venv
|
|
|
|
# 3. Activate it
|
|
source venv/bin/activate
|
|
|
|
# 4. Upgrade pip
|
|
python -m pip install --upgrade pip
|
|
|
|
# 5. Install dependencies
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Verify Installation
|
|
|
|
```bash
|
|
# Check installed packages
|
|
pip list
|
|
|
|
# Test database connection
|
|
python3 -c "import psycopg2; print('✓ psycopg2 works')"
|
|
|
|
# Test FastAPI
|
|
python3 -c "import fastapi; print('✓ FastAPI works')"
|
|
```
|
|
|
|
---
|
|
|
|
## Common Error Messages & Fixes
|
|
|
|
### "No module named 'pip'"
|
|
|
|
```bash
|
|
# Fix:
|
|
python3 -m ensurepip --upgrade
|
|
```
|
|
|
|
### "error: externally-managed-environment"
|
|
|
|
This means your system doesn't allow global pip installs (good!). **Solution:** Use virtual environment:
|
|
|
|
```bash
|
|
./scripts/safe_install.sh --create-venv
|
|
source venv/bin/activate
|
|
./scripts/safe_install.sh --all
|
|
```
|
|
|
|
### "ERROR: Could not build wheels for psycopg2"
|
|
|
|
```bash
|
|
# Use binary version instead:
|
|
./scripts/safe_install.sh psycopg2-binary
|
|
```
|
|
|
|
### "Requirement already satisfied" but import fails
|
|
|
|
```bash
|
|
# You're using system Python instead of venv
|
|
# Fix: Deactivate and reactivate
|
|
deactivate
|
|
source venv/bin/activate
|
|
python -c "import sys; print(sys.prefix)" # Should show venv path
|
|
```
|
|
|
|
---
|
|
|
|
## Database Setup (Quick)
|
|
|
|
```bash
|
|
# 1. Install PostgreSQL (if not installed)
|
|
sudo apt-get install postgresql postgis
|
|
|
|
# 2. Create database
|
|
sudo -u postgres psql -c "CREATE DATABASE giglez;"
|
|
sudo -u postgres psql -c "CREATE USER giglez_user WITH PASSWORD 'password';"
|
|
sudo -u postgres psql -c "GRANT ALL ON DATABASE giglez TO giglez_user;"
|
|
|
|
# 3. Configure environment
|
|
cp .env.example .env.development
|
|
nano .env.development # Edit DATABASE_URL
|
|
|
|
# 4. Create tables
|
|
psql -U giglez_user -d giglez -f scripts/create_schema.sql
|
|
```
|
|
|
|
---
|
|
|
|
## Running the Application
|
|
|
|
```bash
|
|
# 1. Activate virtual environment
|
|
source venv/bin/activate
|
|
|
|
# 2. Start API server
|
|
uvicorn src.api.main:app --reload
|
|
|
|
# 3. Open browser
|
|
# Visit: http://localhost:8000/docs
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Task | Command |
|
|
|------|---------|
|
|
| Create venv | `./scripts/safe_install.sh --create-venv` |
|
|
| Activate venv | `source venv/bin/activate` |
|
|
| Install all deps | `./scripts/safe_install.sh --all` |
|
|
| Install one package | `./scripts/safe_install.sh package_name` |
|
|
| Check environment | `./scripts/safe_install.sh --check` |
|
|
| Create backup | `./scripts/safe_install.sh --backup` |
|
|
| List packages | `pip list` |
|
|
| Deactivate venv | `deactivate` |
|
|
| Start API server | `uvicorn src.api.main:app --reload` |
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Install dependencies (done if you followed above)
|
|
2. 📊 Setup database (see Database Setup section)
|
|
3. 📥 Download datasets: `./scripts/download_rf_test_datasets.sh`
|
|
4. 🗺️ Import with GPS: `./scripts/import_with_african_gps.py --limit 1000`
|
|
5. 🚀 Start server: `uvicorn src.api.main:app --reload`
|
|
6. 🌐 Visit: http://localhost:8000/docs
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
```bash
|
|
# Script help
|
|
./scripts/safe_install.sh --help
|
|
|
|
# Full documentation
|
|
cat docs/INSTALLATION_GUIDE.md
|
|
|
|
# Check logs
|
|
tail -f logs/app.log
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated:** 2026-01-16
|
|
**Tested On:** Ubuntu 22.04, Python 3.9+
|