Viktopia/sonar has 84 GitHub stars and 19 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-20 18:25 UTC. Last push 2026-04-13.
What you can do
- Real-time BLE device scanning and counting
- Manufacturer identification using Nordic Semiconductor's database
- iOS device detection
- Time-series data collection and analysis
Gemessener Sternzuwachs
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- 0
- in 1 month
- Verlauf wird gesammelt
Nettoänderungen in überlappenden Zeiträumen, keine Tagessummen. Fehlende Messwerte bleiben leer. Sterne zeigen Interesse, nicht Qualität.
Über uns
Google Analytics for the real world.
DatenREADME.md
OriginalSonar - BLE Device Counter
A FastAPI-based service for counting and analyzing Bluetooth Low Energy (BLE) devices in proximity. This service provides detailed statistics about nearby BLE devices, including manufacturer identification and device type classification.
📋 Features
- Real-time BLE device scanning and counting
- Manufacturer identification using Nordic Semiconductor's database
- iOS device detection
- Time-series data collection and analysis
- Historical data persistence
- RESTful API endpoints for data access
- Docker support with persistent storage
🚀 Quick Start
Prerequisites
- Python 3.11+
- BlueZ (Linux Bluetooth stack)
- Bluetooth hardware with BLE support
- Proper permissions to access Bluetooth (usually requires root or special capabilities)
Installation
- Clone the repository:
git clone https://github.com/Viktopia/sonar.git
cd sonar
- Choose your installation method:
Docker (Recommended)
docker-compose up -d --build
Local Installation
pip install -r requirements.txt
uvicorn app.main:app --reload
- Verify Installation:
curl http://localhost:8000/health
Note: This project is primarily designed to run on a Raspberry Pi but works on any BlueZ-compatible Linux device with proper Bluetooth permissions.
🛠️ Development
Local Development Setup
- Install dependencies:
pip install -r requirements.txt
- Run the development server:
uvicorn app.main:app --reload
Running Tests
# Run test suite
pytest
# Run with coverage
pytest --cov=app --cov-report=term-missing
📡 API Documentation
Endpoints
GET /latest
Returns the most recent scan results and historical statistics.
Response:
{
"current_scan": {
"unique_devices": 8,
"ios_devices": 5,
"other_devices": 3,
"manufacturer_stats": {
"Apple Inc.": 5,
"Nordic Semiconductor ASA": 3
},
"scan_duration_seconds": 10
},
"last_hour": {
"average_unique_devices": 7.5,
"average_ios_devices": 4.5,
"average_other_devices": 3.0,
"peak_unique_devices": 9,
"peak_ios_devices": 6,
"peak_other_devices": 3,
"manufacturer_stats": {
"Apple Inc.": 5.5,
"Nordic Semiconductor ASA": 3.0
}
}
}
GET /time-series
Get time series data for the last 24 hours.
Query Parameters:
interval_minutes: Time interval between data points (default: 60, min: 1, max: 1440)
Response:
{
"interval_minutes": 60,
"time_series": [
{
"timestamp": "2024-03-20T10:00:00",
"average_unique_devices": 8.0,
"average_ios_devices": 5.0,
"average_other_devices": 3.0,
"peak_unique_devices": 9,
"peak_ios_devices": 6,
"peak_other_devices": 3,
"manufacturer_stats": {
"Apple Inc.": 5.0,
"Nordic Semiconductor ASA": 3.0
}
}
]
}
GET /health
Health check endpoint.
Response:
{
"status": "healthy",
"message": "System requirements met"
}
🐳 Docker Deployment
Prerequisites
- Docker and Docker Compose
- Bluetooth hardware access
- Linux host system (for Bluetooth support)
Running with Docker Compose
- Start the service:
docker-compose up -d
- Access the API:
curl http://localhost:8000/health
Data Management
Backup
docker run --rm -v ble_data:/data -v $(pwd):/backup ubuntu tar czf /backup/ble_data_backup.tar.gz /data
Restore
docker run --rm -v ble_data:/data -v $(pwd):/backup ubuntu tar xzf /backup/ble_data_backup.tar.gz -C /
📊 Data Persistence
The service automatically:
- Saves scan history to disk every hour
- Loads historical data on startup
- Maintains data across container restarts
- Stores data in a Docker volume for persistence