Connectivity & WiFi

WiFi

Note: We usually configure devices for you during setup, so you can skip this section unless you know what you're doing or need to reconfigure your device's network settings.

Device Connectivity Status

Check if your device is online using the main device endpoint:

curl -s \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/

The response includes an is_online field:

{
  "success": true,
  "data": {
    "device_id": "QUBE-ONE-<some-id>",
    "name": "My Device",
    "is_online": true,
    // ... other device properties
  }
}

WiFi Configuration

Setting Primary WiFi Credentials

Configure your device's primary WiFi network (2.4 GHz only):

Endpoint: POST /api/v2/devices/{device_id}/wifi

Request:

curl -s -X POST \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ssid": "MyNetwork", "password": "MySecurePassword"}' \
  https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/wifi

Constraints:

• SSID: Maximum 32 characters
• Password: Maximum 64 characters
• Only 2.4 GHz networks are supported

Response:

{
  "success": true,
  "data": true,
  "message": "WiFi settings updated"
}

Getting Current WiFi Status

Endpoint: GET /api/v2/devices/{device_id}/wifi

curl -s \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/wifi

Response for Primary Network:

{
  "success": true,
  "data": {
    "ssid": "MyNetwork",
    "password": "MySecurePassword",
    "rssi": -45,
    "type": "Primary"
  }
}

Response for Secondary Network (Hotspot Mode):

{
  "success": true,
  "data": {
    "ssid": "qube",
    "password": "12345678",
    "rssi": -50,
    "type": "Secondary"
  }
}

Secondary WiFi Network (Configuration Mode)

When the device cannot connect to the primary WiFi network, it will attempt to connect to a secondary configuration hotspot:

• Expected SSID: qube
• Expected Password: 12345678
• Frequency: 2.4 GHz
• Activation: Press and hold the device button for approximately 5 seconds to enable configuration mode

To use this feature:

1. Create a mobile hotspot or temporary WiFi network with SSID qube and password 12345678
2. Press and hold the device button for ~5 seconds to put it in configuration mode
3. The device will connect to your qube hotspot
4. Use the WiFi configuration API to set new primary network credentials

Network Diagnostics

RSSI Signal Strength

The WiFi status endpoint returns the RSSI (Received Signal Strength Indicator) value:

• Values closer to 0 indicate stronger signal
• Typical ranges:
  • -30 to -50 dBm: Excellent signal
  • -50 to -70 dBm: Good signal
  • -70 to -80 dBm: Weak signal
  • Below -80 dBm: Very weak signal

Device Network Information

For network whitelisting or MAC address filtering, you'll need to obtain the device's MAC address. This information may be available through the device properties or network details. Contact support if you need assistance with MAC address identification for RADIUS server configuration.

Troubleshooting Connectivity

If your device shows as offline:

1. Check WiFi credentials - Use GET /api/v2/devices/{device_id}/wifi to verify settings
2. Signal strength - Check RSSI value; move device closer to router if weak
3. Network compatibility - Ensure your network is 2.4 GHz (5 GHz not supported)
4. Configuration mode - Create a qube hotspot and use configuration mode to reconfigure if needed
5. Device restart - Power cycle the device if connection issues persist

Error Handling

Device offline during configuration:

{
  "success": false,
  "error": {
    "code": "device_not_found",
    "detail": "Network details not found. Device might not be online."
  }
}

Invalid WiFi credentials format:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "detail": [
      {
        "loc": ["ssid"],
        "msg": "ensure this value has at most 32 characters"
      }
    ]
  }
}