Troubleshooting Guide

This guide covers common issues and their solutions.

1. Telemetry Not Appearing on Map

If you are not seeing real-time updates for your devices:

• Check Device Status: In the Devices page, check the "Last Seen" timestamp. If it is "Never," the backend has not yet received a valid packet.

• Verify UDP Ingestion:

  • Ensure your device is sending UDP packets to the correct IP address and Port (usually 1234).

  • Check for firewall rules on your EC2 instance or local network that might be blocking UDP traffic.

• HMAC Authentication:

  • Ensure the shared secret (32-byte HEX) on the device exactly matches the one registered in the AdaTrack backend.

  • Verify that the device's clock is synchronized with a real-time clock (RTC) or GPS time. If the device timestamp is off by more than 5 seconds, the packet will be rejected.

• Decoder Errors:

  • Navigate to Device Profiles and check the "Decoder Logs" for your profile. Any syntax or runtime errors in your JavaScript decoder will prevent the data from being persisted.

2. Dashboard Shows "No Data" (Self-hosted)

This typically indicates an issue with the monitoring stack (Prometheus/Grafana):

• Verify Backend is Running: Run ps aux | grep server or sudo docker ps | grep backend.

• Test Metrics Endpoint: Run curl http://localhost:8080/metrics. It should return a list of Prometheus-formatted metrics.

• Check Prometheus Targets: Visit http://localhost:9090/targets in your browser. The iot-backend target should be UP.

• Grafana Data Source: Ensure the Prometheus data source in Grafana is correctly configured (usually http://prometheus:9090).

3. Geofence Alerts Not Triggering

• Verify GPS Accuracy: Geofence alerts require a valid GPS coordinate. If your device's GPS fix is poor, its reported location may be outside the geofence boundary or have high horizontal dilution of precision (HDOP).

• Check Geofence State: Ensure the geofence is Active and that the device is correctly associated with it.

• Trigger Logic: Remember that geofence alerts are triggered by a crossing event (Entering or Exiting). If a device is already inside a geofence when it is created, an "Entry" event will not be triggered until it first exits and re-enters.

4. Report Generation Failed

• Check Time Range: Ensure the requested report has a valid time range with existing telemetry data.

• Account Quotas: Verify that your account has not exceeded the monthly "Report Generation Quota."

• Storage Configuration: For self-hosted deployments, ensure the backend has write permissions to the /reports directory or that the S3 bucket configuration is correct.

still Having Issues?

Check your backend logs for specific error messages:

# If running with systemd
sudo journalctl -u iot-backend -f

# If running with Docker
docker logs -f adatrack_backend

Look for keywords like [ERROR], [REJECT], or [PANIC].