Troubleshooting

Hardware Issues

Device Not Detected by PlatformIO

• Check USB cable connection and try a different cable
• Install USB drivers from RAK documentation
• Try a different USB port (prefer USB 2.0 ports)
• On Windows, check Device Manager for COM port assignment
• On Linux, ensure user has permissions for USB devices

Firmware Won't Build

• Update PlatformIO: pio upgrade
• Check platformio.ini for correct board configuration
• Verify all required libraries are installed
• Clear build cache: pio run --target clean

LoRaWAN Connection Fails

• Verify credentials in secrets.h match TTN console
• Check that region setting matches your TTN application region
• Ensure antennas are properly connected
• Check TTN console for device activation status
• Monitor serial output for error messages

GPS Not Acquiring Fix

• Ensure GPS antenna has clear view of sky
• Wait several minutes for cold start (first fix can take 5-10 minutes)
• Check antenna connection
• Verify GNSS library configuration in firmware

Web Application Issues

Build Errors

• Clear .next directory and rebuild
• Delete node_modules and reinstall: npm install
• Check Node.js version (requires 18+)
• Verify all environment variables are set in .env.local

Supabase Connection Issues

• Verify NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are correct
• Check Supabase project status in dashboard
• Ensure PostGIS extension is enabled
• Verify database schema has been applied
• Check Supabase logs for connection errors

Map Not Displaying

• Verify NEXT_PUBLIC_MAPBOX_TOKEN is set
• Check Mapbox token permissions and usage limits
• Ensure token has access to required styles
• Check browser console for Mapbox API errors

No Balloons Showing on Dashboard

• Verify webhook is configured in TTN console
• Check webhook URL matches your deployed domain
• Verify webhook format is set to JSON
• Check Vercel function logs for webhook errors
• Ensure telemetry data exists in Supabase
• Check time filters - dashboard shows balloons from last 24 hours

Webhook Issues

Webhook Not Receiving Data

• Verify webhook URL is accessible (test with curl or Postman)
• Check TTN console for webhook delivery status
• Review Vercel function logs for incoming requests
• Ensure webhook format matches expected JSON structure
• Check for CORS or authentication issues

Data Not Appearing in Database

• Check webhook route logs for errors
• Verify payload decoding logic matches firmware encoding
• Check Supabase table permissions and RLS policies
• Verify database schema includes all required columns
• Test direct database insert to isolate webhook issues

Dashboard Issues

Performance Problems

• Switch to 2D map view for better performance
• Reduce number of balloons displayed (adjust time filter)
• Check browser console for JavaScript errors
• Clear browser cache and reload
• Disable browser extensions that might interfere

Timeline Not Working

• Ensure flight path data exists for selected balloon
• Check that telemetry data has valid timestamps
• Verify timeline component is receiving correct props
• Check browser console for errors

Deployment Issues

Vercel Build Fails

• Check build logs for specific error messages
• Verify all environment variables are set in Vercel dashboard
• Ensure package.json has correct build scripts
• Check for TypeScript or linting errors locally first
• Verify Node.js version in Vercel matches local version

Environment Variables Not Working

• Ensure variables are prefixed with NEXT_PUBLIC_ for client-side access
• Redeploy after adding new environment variables
• Check Vercel dashboard for variable typos
• Verify variables are not in .gitignore (they shouldn't be committed, but should be in Vercel)

General Debugging Tips

• Check Logs: Review serial output, browser console, and Vercel function logs
• Test Incrementally: Verify each component works independently
• Use Test Data: Insert test records directly into Supabase to verify dashboard functionality
• Network Tools: Use browser DevTools Network tab to inspect API calls
• Version Check: Ensure all dependencies are up to date