{"id":2737,"date":"2025-08-10T17:57:47","date_gmt":"2025-08-10T17:57:47","guid":{"rendered":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/?p=2737"},"modified":"2025-08-10T17:59:13","modified_gmt":"2025-08-10T17:59:13","slug":"rf-quantum-scythe-websocket-server-documentation","status":"publish","type":"post","link":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/?p=2737","title":{"rendered":"RF QUANTUM SCYTHE &#8211; WebSocket Server Documentation"},"content":{"rendered":"<div class=\"wp-block-image\">\n<figure class=\"aligncenter size-large\"><img data-opt-id=1549604659  fetchpriority=\"high\" decoding=\"async\" width=\"1024\" height=\"666\" src=\"https:\/\/ml6vmqguit1n.i.optimole.com\/w:1024\/h:666\/q:mauto\/f:best\/https:\/\/172-234-197-23.ip.linodeusercontent.com\/wp-content\/uploads\/2025\/08\/image-17.png\" alt=\"\" class=\"wp-image-2739\" srcset=\"https:\/\/ml6vmqguit1n.i.optimole.com\/w:1024\/h:666\/q:mauto\/f:best\/https:\/\/172-234-197-23.ip.linodeusercontent.com\/wp-content\/uploads\/2025\/08\/image-17.png 1024w, https:\/\/ml6vmqguit1n.i.optimole.com\/w:300\/h:195\/q:mauto\/f:best\/https:\/\/172-234-197-23.ip.linodeusercontent.com\/wp-content\/uploads\/2025\/08\/image-17.png 300w, https:\/\/ml6vmqguit1n.i.optimole.com\/w:768\/h:499\/q:mauto\/f:best\/https:\/\/172-234-197-23.ip.linodeusercontent.com\/wp-content\/uploads\/2025\/08\/image-17.png 768w, https:\/\/ml6vmqguit1n.i.optimole.com\/w:1098\/h:714\/q:mauto\/f:best\/https:\/\/172-234-197-23.ip.linodeusercontent.com\/wp-content\/uploads\/2025\/08\/image-17.png 1098w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n<\/div>\n\n\n<pre class=\"wp-block-code\"><code># RF QUANTUM SCYTHE - WebSocket Server Documentation\n\n## Overview\n\nThe RF QUANTUM SCYTHE WebSocket server provides real-time communication between the backend analytics engine and frontend visualization interfaces. It supports authentication, channel-based subscriptions, and bidirectional messaging for live RF signal analysis and visualization updates.\n\n## \ud83d\ude80 Quick Start\n\n### Starting the WebSocket Server\n\n**For page2.html compatibility (Recommended):**\n```bash\n# Use the provided startup script\n.\/start_websocket_for_page2.sh\n\n# Or manually:\nsource \/home\/bgilbert\/rf_quantum_env\/bin\/activate\ncd \/home\/bgilbert\/RF_QUANTUM_SCYTHE_GITHUB\npython websocket_server.py --port 5001 --debug\n```\n\n**For general use:**\n```bash\npython websocket_server.py --port 5800 --debug\n```\n\n### Connecting from page2.html\n\n1. Open page2.html in your browser\n2. Navigate to the \"WebSocket API\" section\n3. Ensure URL is set to: `ws:\/\/localhost:5001\/ws`\n4. Click \"Connect\"\n5. Use \"Authenticate\" for secured endpoints (if --auth flag is used)\n\n## \ud83d\udce1 WebSocket Endpoints\n\n### Primary Endpoints\n\n| Endpoint | Purpose | Description |\n|----------|---------|-------------|\n| `\/ws` | General WebSocket | Main connection for API testing and general communication |\n| `\/ws\/geo` | Geolocation Data | Specialized endpoint for RF signal location and mapping data |\n\n### REST API Endpoints\n\n| Endpoint | Method | Purpose |\n|----------|---------|----------|\n| `\/` | GET | Server info and documentation links |\n| `\/api\/status` | GET | Server status, uptime, and connection statistics |\n| `\/docs` | GET | FastAPI auto-generated documentation |\n\n## \ud83d\udd10 Authentication System\n\n### Authentication Flow\n\n1. **Connect** to WebSocket endpoint\n2. **Send authentication message**:\n   ```json\n   {\n     \"type\": \"auth\", \n     \"api_key\": \"your_api_key_here\"\n   }\n   ```\n3. **Receive confirmation**:\n   ```json\n   {\n     \"type\": \"system\",\n     \"subtype\": \"auth_success\", \n     \"message\": \"Authentication successful\"\n   }\n   ```\n\n### Demo Token\nFor testing purposes, use: `rf_quantum_scythe_demo_token`\n\n## \ud83d\udce2 Message Types\n\n### Client \u2192 Server Messages\n\n#### Authentication\n```json\n{\n  \"type\": \"auth\",\n  \"api_key\": \"rf_quantum_scythe_demo_token\"\n}\n```\n\n#### Subscription\n```json\n{\n  \"type\": \"subscribe\",\n  \"topics\": &#91;\"signal_detected\", \"packet_detected\", \"signal_classification_updated\"]\n}\n```\n\n#### Custom Messages\n```json\n{\n  \"type\": \"custom\",\n  \"data\": {\n    \"command\": \"get_signal_data\",\n    \"parameters\": {\"frequency_range\": \"2.4-2.5GHz\"}\n  }\n}\n```\n\n### Server \u2192 Client Messages\n\n#### System Messages\n```json\n{\n  \"type\": \"system\",\n  \"subtype\": \"auth_required|auth_success|auth_failure|error\",\n  \"message\": \"Human-readable message\",\n  \"timestamp\": 1691668800.123\n}\n```\n\n#### Real-time Updates\n```json\n{\n  \"type\": \"signal_update\",\n  \"data\": {\n    \"frequency\": 2.4e9,\n    \"power\": -45.2,\n    \"location\": {\"lat\": 40.7589, \"lng\": -73.9851},\n    \"classification\": \"WiFi_802.11n\"\n  },\n  \"timestamp\": 1691668800.456\n}\n```\n\n#### Location Updates\n```json\n{\n  \"type\": \"location_update\", \n  \"data\": &#91;\n    {\n      \"id\": \"sdr_001\",\n      \"lat\": 40.7589,\n      \"lng\": -73.9851,\n      \"altitude\": 10.5,\n      \"status\": \"active\"\n    }\n  ]\n}\n```\n\n## \ud83d\udcca Subscription Topics\n\n### Available Topics\n\n| Topic | Description | Data Type |\n|-------|-------------|-----------|\n| `signal_detected` | New RF signal detection | Signal metadata and characteristics |\n| `packet_detected` | Network packet analysis | Packet headers and classification |\n| `signal_classification_updated` | ML classification results | AI\/ML analysis results |\n| `location_update` | SDR location changes | GPS coordinates and status |\n| `alert_triggered` | Security alerts | Threat detection notifications |\n| `spectrum_data` | Real-time spectrum | FFT and waterfall data |\n\n### Subscribing to Topics\n```json\n{\n  \"type\": \"subscribe\",\n  \"topics\": &#91;\"signal_detected\", \"alert_triggered\"]\n}\n```\n\n## \ud83d\udee0 Configuration Options\n\n### Command Line Arguments\n\n```bash\npython websocket_server.py &#91;OPTIONS]\n\nOptions:\n  --port PORT     Port to run server on (default: 5800)\n  --debug         Enable debug mode with auto-reload\n  --auth          Require token authentication for all connections\n  -h, --help      Show help message\n```\n\n### Port Configuration\n\n- **Port 5001**: Recommended for page2.html compatibility\n- **Port 5800**: Default port for general use\n- **Port 8000**: Alternative port (avoid conflicts with other services)\n\n## \ud83d\udcc8 Monitoring &amp; Statistics\n\n### Connection Statistics\nAccess real-time statistics at: `http:\/\/localhost:5001\/api\/status`\n\n```json\n{\n  \"status\": \"online\",\n  \"uptime\": 3600.45,\n  \"connected_clients\": {\n    \"total\": 3,\n    \"channels\": {\n      \"general\": 2,\n      \"geo\": 1,\n      \"admin\": 0\n    }\n  },\n  \"signals_count\": 1247,\n  \"locations_count\": 5\n}\n```\n\n### Logging\n- **Console**: Real-time connection and message logs\n- **File**: `logs\/websocket_server.log` (auto-created)\n- **Level**: INFO (standard), DEBUG (with --debug flag)\n\n## \ud83d\udd27 Integration Examples\n\n### JavaScript Client (page2.html)\n```javascript\nconst ws = new WebSocket('ws:\/\/localhost:5001\/ws');\n\nws.onopen = () =&gt; {\n    console.log('Connected to WebSocket');\n    \/\/ Authenticate\n    ws.send(JSON.stringify({\n        type: 'auth',\n        api_key: 'rf_quantum_scythe_demo_token'\n    }));\n};\n\nws.onmessage = (event) =&gt; {\n    const message = JSON.parse(event.data);\n    console.log('Received:', message);\n};\n```\n\n### Python Client\n```python\nimport asyncio\nimport websockets\nimport json\n\nasync def client():\n    uri = \"ws:\/\/localhost:5001\/ws\"\n    async with websockets.connect(uri) as websocket:\n        # Authenticate\n        auth_msg = {\"type\": \"auth\", \"api_key\": \"rf_quantum_scythe_demo_token\"}\n        await websocket.send(json.dumps(auth_msg))\n        \n        # Subscribe to topics\n        sub_msg = {\"type\": \"subscribe\", \"topics\": &#91;\"signal_detected\"]}\n        await websocket.send(json.dumps(sub_msg))\n        \n        # Listen for messages\n        async for message in websocket:\n            data = json.loads(message)\n            print(f\"Received: {data}\")\n\nasyncio.run(client())\n```\n\n## \ud83d\udea8 Troubleshooting\n\n### Common Issues\n\n1. **Connection Refused**\n   - Ensure WebSocket server is running\n   - Check port number (5001 for page2.html)\n   - Verify firewall settings\n\n2. **Authentication Failures** \n   - Use correct demo token: `rf_quantum_scythe_demo_token`\n   - Ensure --auth flag is set if required\n   - Check message format\n\n3. **No Data Received**\n   - Subscribe to relevant topics first\n   - Check if simulation is enabled\n   - Verify channel subscription\n\n4. **Port Already in Use**\n   ```bash\n   # Kill existing process\n   sudo lsof -ti:5001 | xargs kill -9\n   \n   # Or use different port\n   python websocket_server.py --port 5002\n   ```\n\n### Debug Mode\nRun with `--debug` for detailed logging:\n```bash\npython websocket_server.py --port 5001 --debug\n```\n\n## \ud83d\udcdd Development Notes\n\n### Server Features\n- \u2705 FastAPI-based WebSocket server\n- \u2705 Multi-channel support (general, geo, admin)\n- \u2705 Token-based authentication\n- \u2705 CORS enabled for cross-origin requests\n- \u2705 Connection management and cleanup\n- \u2705 Real-time broadcasting\n- \u2705 Error handling and recovery\n\n### Future Enhancements\n- &#91; ] Database integration for persistent data\n- &#91; ] Advanced authentication (JWT tokens)\n- &#91; ] Rate limiting and connection throttling\n- &#91; ] SSL\/TLS support for production\n- &#91; ] Message queuing for offline clients\n\n---\n\n## \ud83d\udcde Support\n\nFor issues or questions:\n1. Check the console\/log output for error messages\n2. Test connection with the provided test scripts\n3. Verify virtual environment is activated\n4. Ensure all dependencies are installed\n\n**Last Updated**: August 10, 2025  \n**Version**: 1.0.0  \n**Compatible with**: page2.html, RF QUANTUM SCYTHE API Tester<\/code><\/pre>\n","protected":false},"excerpt":{"rendered":"","protected":false},"author":1,"featured_media":2534,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"neve_meta_sidebar":"","neve_meta_container":"","neve_meta_enable_content_width":"","neve_meta_content_width":0,"neve_meta_title_alignment":"","neve_meta_author_avatar":"","neve_post_elements_order":"","neve_meta_disable_header":"","neve_meta_disable_footer":"","neve_meta_disable_title":"","footnotes":""},"categories":[10],"tags":[],"class_list":["post-2737","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-signal_scythe"],"_links":{"self":[{"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/posts\/2737","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2737"}],"version-history":[{"count":2,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/posts\/2737\/revisions"}],"predecessor-version":[{"id":2740,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/posts\/2737\/revisions\/2740"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=\/wp\/v2\/media\/2534"}],"wp:attachment":[{"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2737"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2737"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/172-234-197-23.ip.linodeusercontent.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2737"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}