Troubleshooting and Usage

Troubleshooting & Usage Guide

This guide addresses common operational issues, system behaviors, and usage scenarios across the QuakeGuard infrastructure.

Device stuck in Boot Loop or rebooting constantly: This is usually caused by the ENROLLMENT_TOKEN failing the compile-time #error check, or a hardware exception in the FreeRTOS tasks. Verify your esp32_config.env and re-flash the firmware.
Sensor fails to connect to Wi-Fi: On the first boot, if the ESP32 cannot find the hardcoded network, it will fallback to an Access Point mode (QuakeGuard-Setup). Connect to this AP with your phone to provide the correct network credentials.
I2C Connection Errors (e.g., ADXL345 not found): Double-check the software I2C mapping. Ensure SDA is on GPIO 7 and SCL is on GPIO 8. Remember that the ADXL345 requires 3.3V, not 5V.
Failed Provisioning (Backend rejects registration): If the device prints a 401 Unauthorized or 403 Forbidden during the handshake, ensure the SERVER_HOST in your config points to the correct Cloudflare URL or local IP, and that the backend is actively running.

API returns 429 Too Many Requests: You have triggered the Redis rate limiter (fixed-window, 50 req/s per IP). This is expected during a stress test. Wait 60 seconds for the window to reset.
Worker fails to start (Connection Refused): The worker.py script requires Redis to be active. Ensure docker compose up has fully initialized the Redis and PostgreSQL containers before the worker attempts to connect.
Geographic Zone assigned to "Unknown Region": If your POST /devices/register payload sends latitude=0.0 and longitude=0.0, PostGIS cannot intersect it with a valid country polygon. Hardcode valid GPS coordinates in main.cpp for testing.

WebSocket disconnected / No alerts received: The Expo app features an exponential backoff reconnection strategy. However, if the backend restarts, you may need to force a reconnection by toggling the "Offline Mode" switch in the Settings tab off and on again.
Push Notifications not triggering: Ensure you have granted notification permissions at the OS level. Notifications will only fire for payloads marked as "CRITICAL" with a magnitude $\ge$ 4.5.
AI Report shows "AI Report Unavailable": The report worker transitions to FAILED when inference fails or times out. Verify the ai profile is running (docker compose --profile ai up -d), that Ollama is healthy, and that AI_REPORT_ENABLED=true — see AI Emergency Report Service.