Debugging Guide¶

This guide provides debugging procedures and troubleshooting steps for various components of the Whitebox system.

Debugging Insta360 Connection¶

When working with Insta360 camera integration, you may encounter connection issues or need to verify device behavior. While you can use the frontend UI to get connection status and toggle device on/off to enforce reconnects. This guide focuses on using Postman and WebSocket connections to debug and test the Insta360 Wi-Fi device connection in case of any other serious issues, if they arise.

Prerequisites¶

Compatible USB Wi-Fi interface attached to your system
Insta360 camera powered on and in range
Postman installed (for API testing)

Connecting to Management Channel¶

The management WebSocket channel provides real-time updates about device status changes. Connect to it using a WebSocket client:

ws://10.42.0.1:8000/ws/management/

You'll receive live updates when devices connect, disconnect, or change state.

Testing Procedures¶

Follow these steps to verify Insta360 connection functionality:

1. Add Your Device¶

Use the create endpoint to add your Insta360 device with Wi-Fi connection settings:

POST http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/

Request body:

{
  "codename": "insta360_x4",
  "connection_type": "wifi",
  "connection_settings": {
    "ssid": "X4 2WRTGC.OSC",
    "password": "12345678"
  }
}

Updates should appear in the management channel.

2. Check Device Status¶

Use the status endpoint with your device ID to see the current connection state:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/status?device_id=1

3. Check Wi-Fi Interfaces¶

Use the interfaces endpoint to see all available Wi-Fi interfaces and their current usage:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/interfaces

4. Test Disconnect¶

Hit the disconnect endpoint:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/disconnect?device_id=1

Verify:

Device appears as disconnected in the management channel
status endpoint reflects the disconnected state
interfaces endpoint shows the Wi-Fi interface is now available

5. Test Reconnect¶

Hit the connect endpoint:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/connect?device_id=1

Verify:

Device appears as connected in the management channel
status endpoint reflects the connected state
interfaces endpoint shows the Wi-Fi interface is in use

6. Test with Camera Power Off¶

Power off the Insta360 camera and repeat steps 3-5 above. You should see:

Connection failures when attempting to connect
Appropriate error messages in the management channel
Status endpoints reflecting the disconnected state

7. Test with Camera Power On¶

Power on the Insta360 camera and repeat steps 3-5 again. Connection should succeed and status should update accordingly.

8. Test Multiple Devices (beta, not supported fully)¶

If you have multiple USB Wi-Fi interfaces:

Add additional devices using the create endpoint
Verify each device gets assigned to a different interface
Check that the interfaces endpoint correctly shows which interfaces are in use
Ensure devices can connect/disconnect independently

Note: You won't be able to stream from multiple Insta360 cameras simultaneously as of now, but connection management should work.

9. Test Interface Unavailability¶

Try to connect more devices than you have available Wi-Fi interfaces. Verify that:

Appropriate errors are returned
Error messages indicate no available interfaces
System doesn't attempt to assign multiple devices to the same interface
Existing connections remain stable

Common Issues and Troubleshooting¶

Issue: Wi-Fi interface not detected¶

Symptoms:

Interface doesn't appear in the interfaces endpoint

Solutions:

Verify the USB Wi-Fi adapter is properly connected
Check that the adapter is compatible with your system
Check interface was able to bind to host using ip link show on the host and ensuring wlan0 & wlan1, minimum two interfaces are present
Run docker exec -it backend-dev bash and check with nmcli device wifi list ifname wlan1 to see if the adapter can scan for networks and the SSID of the Insta360 camera appears

Offline Map Tiles Debugging¶

If you are experiencing issues with offline map tiles not displaying correctly in the Whitebox frontend, follow these debugging steps.

Check Tile Server Logs¶

Ensure the tile server is running and check its logs for any errors:

docker compose logs -f tileserver

Check Backend Logs¶

Ensure you don't see any errors in backend logs related to tile serving:

docker compose logs -f backend

Verify Tile Availability¶

Check if the tile file exists in the expected location inside the tile server container:

docker exec -it tileserver bash
ls /data/
# map.mbtiles should be listed

Inspect Network Requests¶

Use browser developer tools to inspect network requests for map tiles. Look for any 404 errors indicating missing tiles.

Monitoring Logs¶

You can monitor various logs to help diagnose issues by following these commands:

# Ensure you are in the whitebox directory
cd whitebox

# And
docker compose logs -f <service-name>

Examples:

# Backend logs
docker compose logs -f backend

# RQ Worker logs
docker compose logs -f rq-worker

List all services with:

docker compose ps